[
https://issues.apache.org/jira/browse/DOXIA-709?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17796866#comment-17796866
]
ASF GitHub Bot commented on DOXIA-709:
--------------------------------------
kwin commented on code in PR #182:
URL: https://github.com/apache/maven-doxia/pull/182#discussion_r1427097303
##########
doxia-core/src/main/java/org/apache/maven/doxia/sink/impl/AbstractSink.java:
##########
@@ -23,12 +23,337 @@
/**
* An abstract base class that defines some convenience methods for sinks.
+ * Also acts as compatibility bridge for Doxia 1.0 methods which have
overridden variants in Doxia > 1.0
Review Comment:
As long as the methods not taking SinkEventAttributes are not deprecated,
this is permanent.
> Clarify usage of overlapping Sink methods
> -----------------------------------------
>
> Key: DOXIA-709
> URL: https://issues.apache.org/jira/browse/DOXIA-709
> Project: Maven Doxia
> Issue Type: Improvement
> Components: Sink API
> Reporter: Konrad Windszus
> Priority: Major
>
> With Doxia 1.1 new methods have been added taking an additional
> {{SinkEventAttributes}} parameter. Semantically there is now an overlap, e.g.
> between {{Sink.sectionTitle1}} and {{Sink.sectionTitle(1, null)}}
> It should be clear from the javadoc when which one is supposed to be called,
> and also which one is the preferred method now.
> E.g. in {{SinkAdapter}} all new Doxia 1.1 methods taking a
> {{SinkEventAttributes}} just forward to the equivalent method not taking it.
> OTOH {{Xhtml5BaseSink}} delegates the other way around (e.g. for
> {{link(String)}}) or does not delegate at all (e.g. for {{sectionTitle(int,
> SinkEventAttributes)}} and {{sectionTitle1()}}).
> That leads to the fact that things are often not rendered consistently
> although from their javadoc they should lead to the same result.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
