Allow javadoc formatting to be skipped.

[sdavids]

This is useful if one uses the AsciiDoc syntax to write one's Javadoc.

https://github.com/asciidoctor/asciidoclet/

[kevinb9n]

We could consider skipping it whenever the first character of doc is =...

[sdavids]

What about field/method comments?

example: Awesome Asciidoctor: Using Asciidoctor In Javadoc Comments

[kevinb9n]

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]

= is equivalent to <h1>

Section Titles (Headings)

/** = the example */
private String example;

is equivalent to:

/** <h1> the example */
private String example;

What I meant:

= is not used to flag 'this is asciidoc' rather than normal javadoc

[kevinb9n]

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]

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]

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]

Why not just have an option to exclude formatting javadoc?

[pettermahlen]

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]

(Off-topic to current issue, since Javadoc has to begin with /**.)

[kevinb9n]

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.