[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781720#comment-17781720
]
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_r1378734859
##########
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
+ * reports as well.
*
- * @param outputDirectory the new output directory
+ * @param outputDirectory the new shared base report output directory
*/
void setReportOutputDirectory(File outputDirectory);
/**
- * @return the current report output directory.
+ * Get the shared base report output directory.
Review Comment:
delete base
##########
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:
I'm not sure the word "base" adds anything here
output of --> the output of
##########
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
+ * reports as well.
*
- * @param outputDirectory the new output directory
+ * @param outputDirectory the new shared base report output directory
Review Comment:
delete "base"
##########
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:
delete "The base location may contain path components
* to better structure the report output". as it's not relevant to this
method. Possibly the interaction of the methods could be described in the class
level comment
##########
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:
This one is a little hard to describe because what the API does is
complicated. On first read, I thought this was just a file name but it's not.
But now I read it a third time and maybe it is just a file name? I don't know.
If it is just a file name, then "Returns the name of the output file that
will be written in {@link #getReportOutputDirectory()}"
If it can contain subdirectories, then "Returns a path relative to {@link
#getReportOutputDirectory()} where the output file will be written."
> 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)
