google / google/styleguide

java: javadoc: Consider clarifying “containing only the aligned leading asterisk”

Open
#820 5 comments 0 reactions 0 assignees View on GitHub
lang:java
Dominant language
HTML
Stars
39.6k
Forks
12.9k
Avg merge
42m
Merged PRs (30d)
15

Description

About Javadoc, the GJSG [states](https://google.github.io/styleguide/javaguide.html#s7.1.2-javadoc-paragraphs): “One blank line—that is, a line containing only the aligned leading asterisk (*)—appears between paragraphs, and before the group of block tags if present.”

Is the intent to prohibit a space after the asterisk? I thought not as the space does not hurt visually and is useful (as reported [here](https://stackoverflow.com/questions/15755671#comment22391924_15755671)), but [others](https://checkstyle.org/checks/javadoc/requireemptylinebeforeblocktaggroup.html#RequireEmptyLineBeforeBlockTagGroup) interpret this differently.

Please consider clarifying, for example by rewording to “a line containing only the aligned leading asterisk (*) _optionally followed by a single space character_”, if this is the intent.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.