You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Same deal -- if you make it recognizable to the tool then we can consider recognizing it. I don't know why the example you linked makes it clear for the class (starting = sign) but not for the method; that seems like a mistake.
Oh. That's too bad. If they're going to diverge from the 20-year standard of what javadoc looks like, they should at least make that divergence detectable. For one thing, they leave a large codebase, where people actually care about and write documentation, out of luck for how it might transition. (Perhaps they figure such codebases don't exist, but... they do!)
What are other arguments for making javadoc formatting optional in google-java-format?
This would be useful to avoid formatting license headers - the various license plugins that exist for maven, gradle, etc., tend to use exact string matches and therefore conflict with google-java-format.
Back to the main topic, I would support this as a command-line option. We push back on options that we see as configuring its formatting choices, but we do have several that merely switch on or off certain of its functions.
Activity
kevinb9n commentedon Mar 17, 2017
We could consider skipping it whenever the first character of doc is
=...sdavids commentedon Mar 17, 2017
What about field/method comments?
example: Awesome Asciidoctor: Using Asciidoctor In Javadoc Comments
kevinb9n commentedon Mar 17, 2017
Same deal -- if you make it recognizable to the tool then we can consider recognizing it. I don't know why the example you linked makes it clear for the class (starting
=sign) but not for the method; that seems like a mistake.sdavids commentedon Mar 17, 2017
=is equivalent to<h1>Section Titles (Headings)
is equivalent to:
What I meant:
=is not used to flag 'this is asciidoc' rather than normal javadockevinb9n commentedon Mar 17, 2017
Oh. That's too bad. If they're going to diverge from the 20-year standard of what javadoc looks like, they should at least make that divergence detectable. For one thing, they leave a large codebase, where people actually care about and write documentation, out of luck for how it might transition. (Perhaps they figure such codebases don't exist, but... they do!)
What are other arguments for making javadoc formatting optional in google-java-format?
sdavids commentedon Mar 17, 2017
As far as I know, the Doclet API does not prescribe the markup of the comment (the StandardDoclet does though.)
Here are two doclets supporting Markdown markup:
https://github.com/Abnaxos/pegdown-doclet
http://doclet.github.io
In both pegdown-doclet and asciidoclet one can even embed PlantUML syntax to generate diagrams (see the example in Awesome Asciidoctor: Using Asciidoctor In Javadoc Comments).
sdavids commentedon Mar 17, 2017
Yes, we have a 20-year standard and yes it is used in most projects.
But if one starts a new project now, one might consider using a more pleasant markup language than HTML.
Also, IntelliJ, Eclipse, Netbeans, and Jindent can be configured to ignore JavaDoc formatting.
hdezninirola commentedon Mar 30, 2017
Why not just have an option to exclude formatting javadoc?
Add flag for skipping javadoc formatting
pettermahlen commentedon Dec 8, 2017
There is also a convention to use
/*-to indicate that a block comment should not be formatted: http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-141999.html#350.This would be useful to avoid formatting license headers - the various license plugins that exist for maven, gradle, etc., tend to use exact string matches and therefore conflict with google-java-format.
kevinb9n commentedon Dec 8, 2017
(Off-topic to current issue, since Javadoc has to begin with
/**.)kevinb9n commentedon Dec 8, 2017
Back to the main topic, I would support this as a command-line option. We push back on options that we see as configuring its formatting choices, but we do have several that merely switch on or off certain of its functions.
Add flag control for javadoc formatting
Add flag control for javadoc formatting