Author Topic: Installation Experience & JavaDoc tool  (Read 3614 times)

Johnco3

  • Community Member
  • Posts: 53
  • Hero Points: 1
Installation Experience & JavaDoc tool
« on: August 21, 2014, 04:24:43 PM »
Initial Problems with Installation:

Slickedit Sprinkles a bunch of extra files in with my existing project files.  It looks like it is trying to generate dependencies between several projects in my solution.

Automated JavaDoc tool is very broken - Under the v18 the following was fine: (Ctrl+Shift+D) would leave the following alone.

Code: [Select]
/**
 * void SLDBProtocol::threadFunction(UtlThreadSafeQueue<SLDBJob>& rJobQueue)
 *
 * thread entry function - pass in shared messaging Job Queue.
 *
 * @param rJobQueue [in,out] shared job queue.
 */
void
SLDBProtocol::threadFunction(UtlThreadSafeQueue<SLDBJob>& rJobQueue)
{
    static const char* method = "SLDBProtocol::threadFunction";
    // all the calls here are synchronous
    while (!mFinished) {
        SLDBJob next;
        rJobQueue.wait_and_pop(next);
        handleJob(next);
    }
}

Now with version 19, when I launch the Edit Doc Comment tool, rJobQueue appeared as "obsolote" in the parameter dropdown list, after dismissing the dialog the @param disappeared and the resultant document comment is per below:

/**
 * void
 * SLDBProtocol::threadFunction(UtlThreadSafeQueue<SLDBJob>&
 * rJobQueue) thread entry function - pass in shared messaging
 * Job Queue.
 */
void
SLDBProtocol::threadFunction(UtlThreadSafeQueue<SLDBJob>& rJobQueue)
{
    static const char* method = "SLDBProtocol::threadFunction";
    // all the calls here are synchronous
    while (!mFinished) {
        SLDBJob next;
        rJobQueue.wait_and_pop(next);
        handleJob(next);
    }
}

I thought that the Template<...> was confusing the documentation wizard, however If I start with an empty comment, per:

Code: [Select]
void
SLDBProtocol::threadFunction(UtlThreadSafeQueue<SLDBJob>& rJobQueue)
{
    static const char* method = "SLDBProtocol::threadFunction";
    // all the calls here are synchronous
    while (!mFinished) {
        SLDBJob next;
        rJobQueue.wait_and_pop(next);
        handleJob(next);
    }
}

Then dismissing the Edit Doc Comment dialog results in the correct behavior of:

Code: [Select]
/**
 *
 * @param rJobQueue
 */
void
SLDBProtocol::threadFunction(UtlThreadSafeQueue<SLDBJob>& rJobQueue)
{
    static const char* method = "SLDBProtocol::threadFunction";
    // all the calls here are synchronous
    while (!mFinished) {
        SLDBJob next;
        rJobQueue.wait_and_pop(next);
        handleJob(next);
    }
}

As a general comment, it would be really useful if there was the ability to customize the automated JavaDoc for parameters, in particular when a parameter is passed in by non const reference, allow the placement of [in,out] generation to be automated.  This is sort of a Doxygen thing (which places the [in,out] before the rJobQueue (I prefer it to be the start of my comment as the parameter names appear shorter) but I have been using it for some time in Visual Slickedit (although I add the [in,out] or [in]/[out] manually).  Another tool, Atomineer Pro Documentation from http://www.atomineerutils.com/ takes automatic document parameter guessing and generation to the next level - automatically prefixing [in,out] to parameters and guessing at what the automated parameter intent should be.  On the other hand, It is far weaker when it comes to flowing the text at predefined columns for which slickedit seems to be far superior. 

The reason that this is so important to me is that I mainly use Slickedit to document my code - relying instead on Visual Studio for the day to day editing/debugging experience.

John

Dennis

  • Senior Community Member
  • Posts: 3955
  • Hero Points: 515
Re: Installation Experience & JavaDoc tool
« Reply #1 on: August 21, 2014, 06:33:55 PM »
I was able to reproduce the problem with the JavaDoc tool and will put together a fix for the next beta drop.

It's normal for SlickEdit to create ".vpw" and ".vpj" and ".vpwhist" and ".vtg" files to correspond to your Visual Studio solution file and project files.  It's just bookkeeping.  The ".vpwhist" file is workspace file history, and the ".vtg" file is the tag database.  In version 19, there is a new workspace option where you can tell SlickEdit to put the history and tag file in a separate directory from the workspace (normally for performance considerations, but you could also do it just for housekeeping considerations).