[
https://issues.apache.org/jira/browse/DOXIA-614?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17259931#comment-17259931
]
ASF GitHub Bot commented on DOXIA-614:
--------------------------------------
elharo commented on a change in pull request #35:
URL: https://github.com/apache/maven-doxia/pull/35#discussion_r552855714
##########
File path:
doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java
##########
@@ -101,7 +101,7 @@
/**
* {@inheritDoc}
*
- * @return a int.
+ * @return a int
Review comment:
I'd just delete this, if there's nothing more to say than the type
##########
File path:
doxia-core/src/main/java/org/apache/maven/doxia/parser/AbstractParser.java
##########
@@ -117,7 +117,7 @@ public void setEmitComments( boolean emitComments )
/**
* <p>isEmitComments.</p>
*
- * @return a boolean.
+ * @return a boolean
Review comment:
ditto
##########
File path: doxia-core/src/main/java/org/apache/maven/doxia/Doxia.java
##########
@@ -41,24 +41,35 @@
* Parses the given source model using a parser with given id,
* and emits Doxia events into the given sink.
*
- * @param source not null reader that provides the source document.
- * You could use <code>newReader</code> methods from {@link
org.codehaus.plexus.util.ReaderFactory}.
- * @param parserId Identifier for the parser to use.
- * @param sink A sink that consumes the Doxia events.
- * @throws org.apache.maven.doxia.parser.manager.ParserNotFoundException
- * if no parser could be found for the given id.
- * @throws org.apache.maven.doxia.parser.ParseException if the model could
not be parsed.
+ * @param source not null reader that provides the source document
+ * @param parserId identifier for the parser to use
+ * @param sink a sink that consumes the Doxia events
+ * @throws ParserNotFoundException if no parser could be found for the
given id
+ * @throws ParseException if the model could not be parsed
*/
void parse( Reader source, String parserId, Sink sink )
throws ParserNotFoundException, ParseException;
+ /**
+ * Parses the given source model using a parser with given id,
+ * and emits Doxia events into the given sink.
+ *
+ * @param source not null reader that provides the source document
+ * @param parserId identifier for the parser to use
+ * @param sink a sink that consumes the Doxia events
+ * @param reference string containing the reference to the source (e.g.
filename)
+ * @throws ParserNotFoundException if no parser could be found for the
given id
+ * @throws ParseException if the model could not be parsed
+ */
+ void parse( Reader source, String parserId, Sink sink, String reference )
Review comment:
probably doesn't matter a great deal, but adding methods to interfaces
is not backwards compatible
----------------------------------------------------------------
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.
For queries about this service, please contact Infrastructure at:
[email protected]
> Support obtaining the source reference in a Doxia Parser
> --------------------------------------------------------
>
> Key: DOXIA-614
> URL: https://issues.apache.org/jira/browse/DOXIA-614
> Project: Maven Doxia
> Issue Type: Improvement
> Components: Core, Modules, Site Renderer (moved to DOXIASITETOOLS)
> Affects Versions: 1.9.1
> Reporter: Abel Salgado Romero
> Priority: Major
>
> Currently, the 'org.apache.maven.doxia.parser.Parser' interface provides 2
> methods that parsers can implement, one with and the other without the source
> reference. However, in reality the one with the reference added in DOXIA-224
> is never invoked, thus making it unusable from maven-site-plugin.
> Methods are:
> * void parse( Reader source, Sink sink )
> * void parse( Reader source, Sink sink, String reference )
>
> 1. Base implementation 'org.apache.maven.doxia.parser.AbstractParser'
> ('doxia-core') of the reference method calls the other, removing the
> reference if it is provided.
> {code:java}
> public void parse( Reader source, Sink sink, String reference )
> throws ParseException
> {
> parse( source, sink );
> }{code}
> 2. In 'org.apache.maven.doxia.DefaultDoxia#parse' ('doxia-core') the parser
> method 'parser (reader, sink)' is called at the end, which means
> 'parser(reader, sink, reference)' is never used.
>
> {code:java}
> public void parse( Reader source, String parserId, Sink sink )
> throws ParserNotFoundException, ParseException
> {
> Parser parser = parserManager.getParser( parserId );
> parser.enableLogging( new PlexusLoggerWrapper( getLogger() ) );
> parser.parse( source, sink );
> }
> {code}
>
> 3. 'org.apache.maven.doxia.Doxia#parse(Reader source, String parserId, Sink
> sink )' and it's implementation 'DefaultDoxia' ('doxia-core') does not
> receive the source reference, so it cannot pass it in any way.
>
> For these 3 reasons,
> 'org.apache.maven.doxia.siterenderer.DefaultSiteRenderer#renderDocument'
> ('doxia-sitetools') who has the source reference is not able to pass it to
> the above components.
> To sum up, the chaing of calls is: DefaultSiteRenderer -> Doxia/DefaultDoxia
> -> Parser implementation (e.g. AbstractParser)
>
> After discussion with [~hboutemy] the proposal is to fix it in several steps
> to avoid using SNAPSHOTS and ensure no breaking points:
> # Change doxia-core components to support new method with "reference", still
> having both methods. This means, changing AbstractParser and it's
> implementations to recieve the "reference". This does not break anything
> since no one is using this param now.
> # Change doxia-sitetools's 'DefaultSiteRenderer' component to pass the
> reference to Doxia/DefautDoxia DOXIASITETOOLS-225.
> # Release new doxia-sitetools version.
> # Once released, modifty doxia-core components to pass the reference and
> remove the (Reader, Sink) method completely. Also, in advance that Parsers
> may need more information about the source, instead of passing "String
> reference", we will pass a new class "SourceMetadata" that encapsulates the
> "String reference. That way we can add more information in the future if
> needed.
>
>
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
