I'll leave it to the current JavaDoc team to rule definitively as regards a new warning, but I note that in raw Markdown a code span may cross line boundaries. For example, the following is legal Markdown that displays as expected:
abc *def ghi* pqr abc `def ghi` pqr If it were to be a new warning, it does not fit into the javac `-Xlint` system (which does not know about Markdown) but nor does it fit into any of the existing `-Xdoclint` groups. If javadoc were to give a warning, why would it do it for code spans (using back ticks) and not for other inline markup? While I accept that not everyone uses a powerful IDE to edit code, to me this does feel like one of the areas where the feedback is best given by an IDE that provides direct support for editing Markdown doc comments. -- Jon On Sun, Jun 21, 2026, at 11:18 PM, [email protected] wrote: > > > >> *From: *"Jonathan Gibbons" <[email protected]> >> *To: *"javadoc-dev" <[email protected]> >> *Cc: *"Remi Forax" <[email protected]> >> *Sent: *Sunday, June 21, 2026 5:15:30 AM >> *Subject: *Re: [External] : Markdown Comments >> Hi Remi, > > Hello, > >> >> Thanks for the field report. I am pleased your list of "pro" is longer than >> your list of "cons". > > :) > >> >> As for your first "cons", the warning you are looking for is >> -Xlint:dangling-doc-comments, which will report all doc comments which are >> not attached to a documentable declaration. which will be the case for any >> `///` lines that become separated from any later `///` lines by an >> intervening `//`. The warning has been available since the introduction of >> Markdown support. > > Okay, the lint warnings for orphan doc comments is on javac, not on javadoc. > > Do you agree that there is still a missing javadoc lint warning for > anti-quote text (`text`) that is not closed ? > >> >> -- Jon > > regards, > Rémi > >> >> >> On Fri, Jun 19, 2026, at 2:28 PM, Remi Forax wrote: >>> Hello, >>> over the last few months, I've developed a small library called LazyLR >>> (runtime grammar parsers) and because it requires Java 25, I use the >>> markdown doc-comments introduced by JEP 467. >>> >>> The overall experience is great, it's better than the traditional >>> doc-comments that mix documentation and HTML tags. >>> >>> Here is my field trip report: >>> >>> Pro: >>> - /// really shine to write one line doc for private methods, the visual >>> overhead is minimal compared to /** ... */ >>> - /// does not requires escaping, even /// inside a /// is correctly >>> recognized >>> - Markdown is a better format than HTML for the documentation (especially >>> lists and tables) >>> - A blank line in markdown is really a blank line, unlike in HTML, so the >>> the doc comments are closer to the rendered javadoc (What you see is closer >>> to what you get) >>> - Code snippets using three backticks (```java) are easier to use than >>> <pre> (no <, no escaping needed) >>> >>> Cons: >>> - If you have 100 lines of /// and one of then is a //, the javadoc will >>> skip all the lines before the '//' without a warning. >>> It should be great if javadoc could emit a warning in that case. >>> - Inline backtick `, are hard to read so it's easy to miss the ending >>> backtick, >>> Again, here, I think I would like a warning if there is no end backtick >>> at the end of the line >>> >>> regards, >>> Rémi >>> >>> Here is a full example: >>> >>> https://github.com/forax/lazylr/blob/master/src/main/java/com/github/forax/lazylr/package-info.java >>> >>> /// # Lazy LR — A Lightweight Runtime LR(1) Parser Library >>> /// >>> /// This package provides all the building blocks to define a context-free >>> grammar, >>> /// tokenize raw text, and parse token streams into structured results at >>> runtime, >>> /// without a separate code-generation step. >>> /// >>> /// ## Core Concepts >>> /// >>> /// A [com.github.forax.lazylr.Grammar] is a validated set of >>> /// [com.github.forax.lazylr.Production] rules plus a >>> /// start [com.github.forax.lazylr.NonTerminal]. >>> /// Productions are built from two kinds of >>> [com.github.forax.lazylr.Symbol]s: >>> /// [com.github.forax.lazylr.Terminal] (a concrete token, e.g. `"+"` or >>> `"num"`) >>> /// and [com.github.forax.lazylr.NonTerminal] (an abstract construct, e.g. >>> `"E"`). >>> /// >>> /// [com.github.forax.lazylr.MetaGrammar] lets you describe tokens, >>> precedence, >>> /// and productions in a compact text instead of building Java objects >>> programmaticaly: >>> /// >>> /// ```java >>> /// var mg = MetaGrammar.load(""" >>> /// tokens { >>> /// num: /[0-9]+/ >>> /// /[ ]+/ >>> /// } >>> /// precedence { >>> /// left: '+' >>> /// left: '*' >>> /// right: '^' >>> /// } >>> /// grammar { >>> /// E: num >>> /// E: E '+' E >>> /// E: E '*' E >>> /// E: E '^' E %prec '^' >>> /// } >>> /// """); >>> /// ``` >>> /// >>> /// The text has three optional sections: >>> /// - **`tokens`**: named terminals (`name: /regex/`) and unnamed >>> /// skip patterns (`/regex/`). >>> /// - **`precedence`**: `left:` or `right:` lines, lowest first, >>> /// multiple terminals per line share the same level. >>> /// - **`grammar`**: BNF-style rules; quoted literals like `'+'` are >>> /// auto-registered as terminals. >>> /// Lines with no right-hand side are epsilon productions, >>> /// `%prec TOKEN` overrides a production's default precedence. >>> /// >>> /// ## Typical Usage >>> /// >>> /// ```java >>> /// // 1. Load the grammar >>> /// MetaGrammar mg = MetaGrammar.load(grammarText); >>> /// >>> /// // 2. Optionally verify for conflicts >>> /// mg.verify(); >>> /// >>> /// // 3. Parse and evaluate >>> /// String inputText = ... >>> /// var result = mg.parse(inputText, new MyVisitor()); >>> /// ``` >>> /// >>> /// ## Key Classes >>> /// [com.github.forax.lazylr.LALRVerifier] performs a full offline LALR(1) >>> /// analysis and can print the complete state automaton with conflict >>> markers. >>> /// This is the class used by >>> [com.github.forax.lazylr.MetaGrammar#verify()]. >>> /// >>> /// [com.github.forax.lazylr.Lexer] converts a `CharSequence` into >>> /// a lazy `Iterator<Terminal>` using a longest-match rule, ties >>> /// broken by declaration order. >>> /// >>> /// [com.github.forax.lazylr.Parser] implements a lazy LR(1) algorithm: >>> /// states are computed on demand. >>> /// Shift/reduce conflicts are resolved via a >>> [com.github.forax.lazylr.Precedence] map; >>> /// unresolved conflicts cause a [com.github.forax.lazylr.ParsingException] >>> /// during parsing. >>> /// A call to >>> [com.github.forax.lazylr.MetaGrammar#parse(java.lang.CharSequence, >>> com.github.forax.lazylr.Visitor)()] >>> /// creates a lexer and a parser. >>> /// >>> /// [com.github.forax.lazylr.Visitor] maps terminal and productions to >>> typechecked methods. >>> /// When a terminal is shifted, the corresponding terminal method is called. >>> /// When a production is reduced, the production method is called with the >>> values >>> /// of the symbols of the production in left-to-right order. >>> /// >>> [com.github.forax.lazylr.Visitor#reflect(java.lang.invoke.MethodHandles.Lookup, >>> com.github.forax.lazylr.Visitor)] >>> /// creates an evaluator from a visitor using reflection. >>> /// >>> /// [com.github.forax.lazylr.Evaluator] maps parse events to a result >>> /// of type `T`: `evaluate(Terminal)` is called on every shift, >>> /// `evaluate(Production, List<T>)` on every reduction. >>> /// For event-driven use without a result, prefer >>> [com.github.forax.lazylr.ParserListener]. >>> /// >>> /// ## Thread Safety >>> /// All classes are immutable and thread-safe except >>> [com.github.forax.lazylr.Parser], >>> /// which is stateful and bound to the thread that uses it. >>> /// >>> /// [com.github.forax.lazylr.MetaGrammar] is thread-safe and can be shared >>> globally. >>> /// >>> /// For concurrent workloads, you can share a >>> [com.github.forax.lazylr.ParserFactory] >>> /// and call [com.github.forax.lazylr.ParserFactory#createParser()] >>> /// once per thread. >>> /// >>> /// @see com.github.forax.lazylr.Terminal >>> /// @see com.github.forax.lazylr.Production >>> /// @see com.github.forax.lazylr.Grammar >>> /// @see com.github.forax.lazylr.MetaGrammar >>> /// @see com.github.forax.lazylr.Visitor
