[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782126#comment-17782126
]
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_r1380023006
##########
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:
Specific actionable context is useful, but too much "business need" is just
wasted words. Common examples:
* in order to improve performance
* in order to improve customer service
* in order to better serve you
None of these actually explain anything. Here don't just say "to better
structure the report output" but explain how the report output structure is
changed, or say nothing at all. I don't know if this is accurate but something
like "to divide the report documents into separate subdirectories" would be
more concrete. "to better structure the report output" is not a user story and
does not explain the business value.
> 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)
