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.
/**
* 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:
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:
/**
*
* @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