Add support for markdown javadoc#433
Conversation
Generate changelog in
|
|
Thanks for your interest in palantir/javapoet, @Goldmensch! Before we can accept your pull request, you need to sign our contributor license agreement - just visit https://cla.palantir.com/ and follow the instructions. Once you sign, I'll automatically update this pull request. |
|
@pkoenig10 could this be merged please? |
pkoenig10
left a comment
pkoenig10
left a comment
There was a problem hiding this comment.
Sorry for the delay here. Approach generally looks good, couple of more minor comments.
| // Emit a newline character. Make sure blank lines in Javadoc & comments look good. | ||
| if (!first) { | ||
| if ((javadoc || comment) && trailingNewline) { | ||
| if ((comment != null) && trailingNewline) { |
There was a problem hiding this comment.
| if ((comment != null) && trailingNewline) { | |
| if (comment != null && trailingNewline) { |
| return JavaFile.builder(tacosPackage, typeSpec).build().toString(); | ||
| } | ||
|
|
||
| private String toStringWithMarkdownJavadocs(TypeSpec typeSpec) { |
There was a problem hiding this comment.
| private String toStringWithMarkdownJavadocs(TypeSpec typeSpec) { | |
| private String toStringWithMarkdownJavadoc(TypeSpec typeSpec) { |
| To output Markdown styled Javadoc (see [JEP 467](https://openjdk.org/jeps/467)), | ||
| th method `useMarkdownJavadoc()` of the `JavaFile` builder has to be called: |
There was a problem hiding this comment.
| To output Markdown styled Javadoc (see [JEP 467](https://openjdk.org/jeps/467)), | |
| th method `useMarkdownJavadoc()` of the `JavaFile` builder has to be called: | |
| To emit Markdown Javadoc (see [JEP 467](https://openjdk.org/jeps/467)), | |
| use `JavaFile.Builder.useMarkdownJavadoc()`: |
| javaFile.writeTo(System.out); | ||
| ``` | ||
|
|
||
| which outputs: |
There was a problem hiding this comment.
nit: consistent wording
| which outputs: | |
| Which generates this: |
| ```java | ||
| TypeSpec emptyClass = TypeSpec.classBuilder("EmptyClass") | ||
| .addJavadoc("# Empty Class\n" | ||
| + "\n" | ||
| + "A representation of nothing: /* empty */\n") | ||
| .addJavadoc("\n") | ||
| .addJavadoc("This is not to be confused with the [$T] datatype which\n" | ||
| + "is an uninstantiable placeholder class to hold a reference\n" | ||
| + "to the *Class* object representing the Java keyword `void`.\n", Void.class) | ||
| .build(); | ||
|
|
||
| JavaFile javaFile = JavaFile.builder("com.example.empty", emptyClass) | ||
| .useMarkdownJavadoc() // sets the Markdown output flag | ||
| .build(); | ||
|
|
||
| javaFile.writeTo(System.out); | ||
| ``` | ||
|
|
||
| which outputs: | ||
|
|
||
| ```java | ||
| package com.example.empty; | ||
|
|
||
| import java.lang.Void; | ||
|
|
||
| /// # Empty Class | ||
| /// | ||
| /// A representation of nothing: /* empty */ | ||
| /// | ||
| /// This is not to be confused with the [Void] datatype which | ||
| /// is an uninstantiable placeholder class to hold a reference | ||
| /// to the *Class* object representing the Java keyword `void`. | ||
| class EmptyClass { | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Can we update this to use the same example (or as similar as possible) as in the non-Markdown example?
| } | ||
|
|
||
| @Test | ||
| public void withParameterMarkdownJavaDoc() throws IOException { |
There was a problem hiding this comment.
This test feels somewhat arbitrary - we don't have similar tests for the other types which can contain Javadoc (ex FieldSpec or ParameterSpec). It also requires this awkward TestUtil.codeWriterWithMarkdownJavadoc, which I'd prefer to avoid introducing.
I think we can just remove this test. It's sufficient to test CodeWriter and JavaFile.
| } | ||
|
|
||
| @Test | ||
| public void recordWithMarkdownJavadoc() { |
There was a problem hiding this comment.
These tests should probably be on JavaFileTest, not TypeSpecTest - the useMarkdownJavadoc option is part of JavaFile.
| return JavaFile.builder(tacosPackage, typeSpec).build().toString(); | ||
| } | ||
|
|
||
| private String toStringWithMarkdownJavadocs(TypeSpec typeSpec) { |
There was a problem hiding this comment.
| private String toStringWithMarkdownJavadocs(TypeSpec typeSpec) { | |
| private String toStringWithMarkdownJavadoc(TypeSpec typeSpec) { |
3 participants
closes #234
Just adds the changes from #390
( I can't find the time to setup the project on my nixos machine currently, so hopefully all changes are still compatible)