| Author |
 Topic  |
|
|
zelka2member
New Member
7 Posts |
 Posted - May 10 2007 : 02:58:01 AM
|
We are using JavaDoc in our projects and we modified "Document Mehtod" to suit our policies. This project is long term, some parts contains 10 years old source code. So we daily refactor our code to serve new requests.
Document Method is great, bu we would also highly appreciated something like "Maintain Method Documentation" which would keep existing documentation comments and added non existing parameters.
It would be also great if "Document Method" could omit @returns tag when documenting function returning void (something as if in AutoText). |
|
|
feline
Whole Tomato Software
United Kingdom
19021 Posts |
Posted - May 10 2007 : 07:51:47 AM
|
I had the same thought about void functions and Document Method myself:
case=1755
I understand the appeal of VA "checking" the existing comment, the problem is understanding that a given parameter has already been documented. In general we cannot make any helpful assumptions about the shape or nature of the comment.
When this is happening, are the current comments in the same form as the Document Method autotext? If so then asking VA to check the parameter line in the Document Method autotext rule against the current comment block is an option. |
zen is the art of being at one with the two'ness |
 |
|
|
zelka2member
New Member
7 Posts |
Posted - May 10 2007 : 08:05:26 AM
|
| That is what I meant in consequence: VA can use Document Method autotext entry as a parsing pattern to check if preceding comment is a document one. Then it should be possible to maintain params in document block, although it is still not a trivial task. |
|
|
|
sl@sh
Tomato Guru
Switzerland
204 Posts |
Posted - May 11 2007 : 05:16:42 AM
|
Well, VA doesn't really need to parse the pattern, only compare any line of documentation it is about to generate with the already existing comment block. If the line already exists, it likely makes no sense to duplicate it.
This of course should only be done with non-static lines - it's quite possible an autotext entry contains multiple trivial static lines such as " * " or " /////////////..." |
|
|
|
feline
Whole Tomato Software
United Kingdom
19021 Posts |
Posted - May 11 2007 : 08:43:01 AM
|
sl@sh this is true, but for now I would like to stop this idea from growing to big 
The idea of scanning the comment block attached to a function and simply adding any missing parameter lines is interesting enough, since we have $MethodArg$, $MethodArgName$ and $MethodArgType$ to consider, which can be combined in various manors.
For simple cases this is easy, but surround these with free text, and use "standard" words as variable names, and I can already see plenty of scope for edge cases.
If we say this only checks parameters, and only checks the start of the line, upto the last autotext symbol, then it should do what we need here. So comments like:
// \\Param $MethodArgName$ free text here
would be checked, but if the user had edited this after it was entered so it became:
// free text here \\Param $MethodArgName$
then I would not be surprised if VA re-generated this parameter line.
Does this seem useful enough? |
zen is the art of being at one with the two'ness |
|
|
|
zelka2member
New Member
7 Posts |
Posted - May 11 2007 : 09:05:11 AM
|
I think that it would be just enough, because
// free text here \\Param $MethodArgName$
is not how good JavaDoc comment should look like, anyway. Intelligence to cope with this is too complex, seems fragile to me and has not much effect.
On the other hand I believe that VA will be able to cope with something like this:
/**
\\brief some text
Some more text.
\\param a whatever
\\param b whatever
\\see some link
*/
int foo(int x,int b, inc); //originally void foo(int a,int b);
VA should not remove anything. It should just add new parameters. If function changes from void to returning for example int then it could also add \\returns tag. That's all. So expected result for me is:
/**
\\brief some text
Some more text.
\\param a whatever
\\param b whatever
\\param x
\\param c
\\see some link
\\returns
*/
int foo(int x,int b, inc);
|
|
|
|
feline
Whole Tomato Software
United Kingdom
19021 Posts |
Posted - May 11 2007 : 11:28:47 AM
|
This sounds reasonable to me. Just so people are aware, I am not expecting VA to understand that you have renamed a parameter or re-ordered them. This is starting to get into tricky territory.
I have put in a feature request for updating Document Method comments:
case=6535 |
zen is the art of being at one with the two'ness |
|
|
|
sl@sh
Tomato Guru
Switzerland
204 Posts |
Posted - May 14 2007 : 04:03:41 AM
|
I agree that you can produce all kinds of edge cases by providing custom Autotext entries. However, these shouldn't concern you since it's already possible to produce garbage with wrong autotext entries.
Everyone editing Autotext should be aware that it's just as prone to errors as standard source code, and that sometimes the error(s) won't be too obvious to detect. The only 'bad' thing about such an improvement to Autotext would be that some custom Autotext entries already in existance might be broken. So it's possible *someone* will complain. (not me  ) |
|
|
|
feline
Whole Tomato Software
United Kingdom
19021 Posts |
Posted - May 14 2007 : 10:37:45 AM
|
Based on a few years experience here, someone will always complain, if only to complain that the feature doesn't give them free chocolate and make then a coffee while it is at it
Get most of the people happy most of the time... if we can do this we are doing well |
zen is the art of being at one with the two'ness |
|
|
| |
Topic |
|
Document Method
