On Thu, Jan 19, 2023 at 5:56 PM Mark Thomas <ma...@apache.org> wrote: > > 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?
Ok for the first. Personally: - No opinion at all on javadoc formatting. - Code formatting is important, but the rules in place were more than enough to satisfy me. So no opinion on going further. Rémy > > Mark > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org > For additional commands, e-mail: dev-h...@tomcat.apache.org > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org
