apache / apache/maven-doxia

[DOXIA-712] Add validation capability to Sink API

Open
#849 2 comments 0 reactions 0 assignees View on GitHub
enhancement priority:major
Dominant language
Java
Stars
34
Forks
54
Avg merge
1d 12h
Merged PRs (30d)
16

Description

**[Konrad Windszus](https://issues.apache.org/jira/secure/ViewProfile.jspa?name=kwin)** opened **[DOXIA-712](https://issues.apache.org/jira/browse/DOXIA-712?redirect=false)** and commented

The Sink API comes with several limitations with regards to valid order of events/method calls and valid parametrization. Those are documented in the javadoc of the Sink interface but are complex to follow. This includes

- certain start events need to be followed by an according end event
- `sectionTitle(int,SinkEventAttributes)` needs to be directly preceded by `section(int,SinkEventAttributes)` with the same first argument.
- certain rules for sequence of events for `table`, `list` (numbered, non-numbered and definition) and `figure`
- validation of certain common parameters like `level` or `SinkEventAttributes` for valid values

As we encourage the direct usage of the Sink API for report mojos there should be a way for mojo authors to quickly crosscheck whether they used the Sink API in a correct way.

---

**Issue Links:**
- [DOXIA-711](https://issues.apache.org/jira/browse/DOXIA-711) Introduce SinkWrapper with factory
(_**"is blocked by"**_)
- [DOXIA-699](https://issues.apache.org/jira/browse/DOXIA-699) Xhtml5Parser may emit sectionX() without sectionX_() when using both \ and \

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the Sink interface Javadoc and the linked DOXIA-711 issue about introducing SinkWrapper with a factory. The work is done when Sink API event ordering and parameter rules can be checked through the proposed validation capability.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.