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]

Reply via email to