[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782293#comment-17782293
]
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_r1380634183
##########
src/main/java/org/apache/maven/reporting/MavenReport.java:
##########
@@ -53,9 +53,10 @@ 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 path relative to {@link #getReportOutputDirectory()} where the
report's main output
+ * file will be written. The last component is expected to be a basename
only.
Review Comment:
OK, so I indeed did not understand what "basename" meant in this context,
which is de facto evidence that this isn't clear enough. Either define
"basename" as the "filename without an extension or period" or perhaps write
something like, "The last component is the name of the file without any
extension. The extension (.pdf, .html, etc.) will be added by the sink. For
example, repodocs/subtext/analysis_report"
though perhaps this is hard to explain because the API itself is weird. I
rarely encounter a path to a file that includes directories and file anme but
not file extension.
> 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)
