Skip to content
This repository has been archived by the owner on Oct 10, 2024. It is now read-only.

Added support for multiline comments #759

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Added support for multiline comments #759

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion src/main/java/com/squareup/javapoet/MethodSpec.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -461,7 +461,12 @@ public Builder addCode(CodeBlock codeBlock) {
}

public Builder addComment(String format, Object... args) {
code.add("// " + format + "\n", args);
String[] lines = format.split("\\R");
code.add("/*\n");
for (String line : lines) {
code.add("* " + line + "\n");
}
code.add("**/\n");
return this;
}

Expand Down
38 changes: 38 additions & 0 deletions src/test/java/com/squareup/javapoet/MethodSpecTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -456,6 +456,44 @@ static void staticMethod() {
"}\n");
}

@Test public void multilineComments() {
MethodSpec main = MethodSpec.methodBuilder("main")
.addModifiers(Modifier.PUBLIC, Modifier.STATIC)
.returns(void.class)
.addParameter(String[].class, "args")
.addComment("Hello\nmultiline\ncomments!")
.addStatement("$T.out.println($S)", System.class, "Hello, JavaPoet!")
.build();

assertThat(main.toString()).isEqualTo("" +
"public static void main(java.lang.String[] args) {\n" +
" /*\n" +
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest using the following syntax for inline comments:

public static void main(String[] args) {
  // Hello
  // multiline
  // comments!
}

The /** */ is most frequently used for Javadoc, so generating it inside a method body feels awkward.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While /** is for javadoc, /* is actually the intended multi-line comment syntax: https://www.oracle.com/technetwork/java/javase/documentation/codeconventions-141999.html

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The last revision to this document was made on April 20, 1999

Copy link
Contributor

@octylFractal octylFractal Jan 27, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's fine if you would prefer not to have it, but that syntax is valid multi-line comment syntax. You can look at other sources and they all distinguish multi-line comments and JavaDoc comments by the extra asterisk. It's not a valid argument to dismiss this by claiming it as JavaDoc.

Edit: see e. g. Wikipedia: https://en.wikipedia.org/wiki/Javadoc#Structure_of_a_Javadoc_comment

Copy link
Author

@devsh0 devsh0 Jan 27, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The multiline comment syntax is valid Java as @octylFractal pointed out. It's common to see single line comments completely replaced by block comments throughout source code. The one that's used for JavaDocs begin with slash followed by two asterisks. /* */ and /** */ are two entirely different things. See here for more information.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I totally confused the two. My preference is still for // - that's less lines and feels more common to me. I haven't seen the /* */ form used in method bodies in a long while.

" * Hello\n" +
" * multiline\n" +
" * comments!\n" +
" **/\n" +
" java.lang.System.out.println(\"Hello, JavaPoet!\");\n" +
"}\n");
}

@Test public void singleLineComments() {
MethodSpec main = MethodSpec.methodBuilder("main")
.addModifiers(Modifier.PUBLIC, Modifier.STATIC)
.returns(void.class)
.addParameter(String[].class, "args")
.addComment("Hello single line comments!")
.addStatement("$T.out.println($S)", System.class, "Hello, JavaPoet!")
.build();

assertThat(main.toString()).isEqualTo("" +
"public static void main(java.lang.String[] args) {\n" +
" /*\n" +
" * Hello single line comments!\n" +
" **/\n" +
" java.lang.System.out.println(\"Hello, JavaPoet!\");\n" +
"}\n");
}

private static CodeBlock named(String format, Map<String, ?> args){
return CodeBlock.builder().addNamed(format, args).build();
}
Expand Down