Hi all,
Ever since the first CheckStyle rules were added, I have been looking at
the options for using my IDE (Eclipse) to fix the code so it meets the
rules. The results until today have been mixed. Some stuff gets fixed
but other stuff gets broken.
Today, however, I made progress. I think I have a Eclipse Formatter
configuration that would enable us to turn on a number of the rules that
are currently commented out (indentation, operator at end of line, etc)
and auto format the code to fix any issues without messing up too much
other stuff.
I'd like to start testing out the formatter by reformatting files before
I work on them. However, before I do that I was wondering whether we
wanted to format the Javadoc as well - especially given the recent
Javadoc rules added to CheckStyle.
With that in mind, what do folks think about increasing the comment
width from 80 to 120 to match the code?
After that, my thinking is:
- blank line between description and tags (param, return, throws etc)
- blank line between different tag types (separate param, return etc)
Those are the easy ones. There are lots of options for aligning tags.
Personally, I am looking for clarity while still using space efficiently
so I prefer that parameter and throws descriptions don't start on a new
line after a tag.
With a longer permitted line for Javadoc I think we can:
- align descriptions grouped by type
- indent tag descriptions
That would give Javadoc that looks a bit like this but not as condensed
as I have used a much shorter max line length:
/**
* Method description. May be short or long.
*
* @param first The first parameter. For an optimum result, this
* should be an odd number between 0 and 100.
* @param second The second parameter.
*
* @return The result of the foo operation, usually an even number
* within 0 and 1000.
*
* @throws Exception when the foo operation cannot be performed
* for one reason or another.
*/
With the longer line length, I suspect most tag descriptions won't need
to wrap. However, if we are worried about long exception names or
parameter names causing problems we could use:
/**
* Method description. May be short or long.
*
* @param first The first parameter. For an optimum result, this
* should be an odd number between 0 and 100.
* @param second The second parameter.
*
* @return The result of the foo operation, usually an even number
* within 0 and 1000.
*
* @throws Exception when the foo operation cannot be performed
* for one reason or another.
*/
I think I prefer the first but could live with either.
Thoughts?
Mark
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
