slachiewicz opened a new pull request, #1126: URL: https://github.com/apache/maven-doxia/pull/1126
Adds `SinkContractValidator`, a `SinkWrapper` that checks the events sent to a sink against the rules the `Sink` Javadoc states and the canonical event sequences it shows, so report authors and parser developers can check their use of the Sink API with any sink implementation. Fixes #849. The following points are not visible in the diff: - It is opt-in. Nothing registers the wrapper or `SinkContractValidatorFactory`; a caller wraps a sink or adds the factory to a parser. - Fail-fast mode throws `SinkContractViolationException` before the event is forwarded. Collect mode forwards everything and keeps the messages. - A parser never closes the wrapper it creates, so elements left open are reported by `finish()`, which `close()` also calls. With the factory, call its `finish()` or `getViolations()` after each document and `reset()` before the next one. - Anchor names follow `DoxiaUtils.isValidId`, as Doxia's sinks do, which is not the SGML NAME rule of the Javadoc: a leading underscore passes and a colon does not. Link names are parsed with `java.net.URI`. - Not checked, because the Javadoc is silent or only links the constants: numbering styles of `numberedList`, `title`, `author` and `date` outside `head`, a `section` that skips a level, and the per-element attribute lists. - `Sink#inline` and `Sink#text` now list `code` among the semantics values; `SinkEventAttributeSet.Semantics.CODE` existed, the Javadoc did not mention it. - The Javadoc says `@since 2.3.0`, while the POM is still at 2.2.1-SNAPSHOT. Run in collect mode over the modules' `test.*` sample documents, the validator reports nothing for APT and Markdown and the following for the other parsers, which this PR does not change: - FML: `FmlParser` emits an anchor between `section1` and `sectionTitle1`, where the Javadoc wants the title first (10 cases). - XDoc and XHTML5: `tableCaption` is emitted inside `tableRows`, where the Javadoc puts it before or after them (one case each). `WellformednessCheckingSink` in the tests and `AbstractParserTest` are unchanged. --- To make clear that you license your contribution under the [Apache License Version 2.0, January 2004](https://www.apache.org/licenses/LICENSE-2.0) check one of the following: - [x] I hereby declare this contribution to be licensed under the [Apache License Version 2.0, January 2004](https://www.apache.org/licenses/LICENSE-2.0) - [x] I hereby declare that I have filed an [Apache Individual Contributor License Agreement](https://www.apache.org/licenses/icla.pdf). -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
