New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Support re-writing multiline docstrings into their multiline form #974
Comments
I agree with your examples, however the trade-off is that it destroys helpful ascii diagrams embedded in javadoc. Verbose javadoc formatting is more common, but not terribly frictionful, where breaking spefically-formatted structures is less common, but much more frictionful when it occurs. Our https://github.com/palantir/goethe wrapper around palantir-java-format for javapoet does format javadoc as you describe above, we have the capability, but I don't think the trade-off is correct to turn it on for human-authored code. What do you think? |
FWIW the Google Java Style guide notes the existence of the single-line pattern but does not endorse it:
https://google.github.io/styleguide/javaguide.html#s7.1.1-javadoc-multi-line (I happen to prefer the single-line form) google-java-format joins to a single line if it fits within 100 characters: https://github.com/google/google-java-format/blob/38de9c4e05bc871496c232c1ccbfc4be06a580e2/core/src/test/java/com/google/googlejavaformat/java/JavadocFormattingTest.java#L395-L449 |
Probably ascii diagrams should be wrapped in |
Would this destroy an ascii diagram? /**
* This is
* a silly
* docstring.
*/
public static boolean example() wdyt? |
I often wish that people would write something like:
rather than:
We could compute whether it would fit on one line and rewrite it if it would. This would only apply to the case of multi-line docstrings that contain a single line. i.e. it would not include:
The text was updated successfully, but these errors were encountered: