[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781953#comment-17781953
]
ASF GitHub Bot commented on MSHARED-1326:
-----------------------------------------
kriegaex commented on code in PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#discussion_r1379470012
##########
src/main/java/org/apache/maven/reporting/MavenReport.java:
##########
@@ -84,14 +86,17 @@ public interface MavenReport {
String getDescription(Locale locale);
/**
- * Set a new output directory. Useful for staging.
+ * Set a new shared base report output directory. This directory may
contain output of other
Review Comment:
@elharo: It adds the notion that not necesarily all reports end up directly
in that directory, but that they can also end up in subdirectory. A base
directory is the flipside of the medal regarding the term subdirectory. Of
course, without the "base" prefix, that would still hold true, but like I said
in an earlier comment: Maximally terse descriptions are not always ideal from a
reader's perspective. BTW, the reader inevitably knows way less about the
meaning of parameters than the provider. She is also unlikely to read all
documentation, but only as little as possible to solve her problem or implement
her use case. I.e., she does not have the full context. And even if she does,
she is unlikely to remember all of it.
> 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)
