[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781963#comment-17781963
]
ASF GitHub Bot commented on MSHARED-1326:
-----------------------------------------
elharo commented on code in PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#discussion_r1379489332
##########
src/main/java/org/apache/maven/reporting/MavenReport.java:
##########
@@ -53,7 +53,9 @@ public interface MavenReport {
void generate(Sink sink, Locale locale) throws MavenReportException;
/**
- * Get the base name used to create report's output file(s).
+ * Get the output name denoting a base location relative to the {@link
#getReportOutputDirectory()}
+ * used to create the report's main output file. The base location may
contain path components
Review Comment:
From a user's perspective "to better structure the report output" adds
nothing. Would anyone expect it to be "to worse structure the report output?"
If not, then this means nothing.It's not redundant. It doesn't add or repeat
anything.
##########
src/main/java/org/apache/maven/reporting/MavenReport.java:
##########
@@ -53,7 +53,9 @@ public interface MavenReport {
void generate(Sink sink, Locale locale) throws MavenReportException;
/**
- * Get the base name used to create report's output file(s).
+ * Get the output name denoting a base location relative to the {@link
#getReportOutputDirectory()}
Review Comment:
OK, so maybe it's a directory name? All of this should be laid out in the
docs. What might help is a longish class comment explaining where the report
files go and how they're configured.
> Improve (documentation on) MavenReport interface/AbstractMavenReport class
> --------------------------------------------------------------------------
>
> Key: MSHARED-1326
> URL: https://issues.apache.org/jira/browse/MSHARED-1326
> Project: Maven Shared Components
> Issue Type: Task
> Components: maven-reporting-api
> Affects Versions: maven-reporting-impl-4.0.0-M11,
> maven-reporting-api-4.0.0-M8
> Reporter: Michael Osipov
> Assignee: Michael Osipov
> Priority: Major
> Fix For: maven-reporting-api-4.0.0-M9,
> maven-reporting-impl-4.0.0-M12
>
>
> Based on a
> [discussion|https://lists.apache.org/thread/6yxlvbhb7odfylfgjgzbvmvxg0vry20b]
> with [~kriegaex], there are few conceptional or documentational issues with
> the {{MavenReport}} interface:
> * {{#getOutputName()}} does not clearly say that is actually an optional base
> *path* and base name (base location) of the report item from a reporting
> output directory. It needs at least a doc update and maybe even a rename to
> {{#getOutputPath()}}/{{#getOutputPathLocation()}}?
> * Both {{#setReportOutputDirectory(File outputDirectory)}} and
> {{#getReportOutputDirectory()}} documentation imply tha this directory solely
> refers to this single report, but that is not correct. It refers to root
> directory which contains all possibly generated reports. A shared directory,
> not exclusive one. Consider your report generates in a subdir, then these do
> *not* refer to it, but to its parent.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
