[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17783373#comment-17783373
]
ASF GitHub Bot commented on MSHARED-1326:
-
asfgit closed pull request #25: [MSHARED-1326] Improve (documentation on)
AbstractMavenReport class
URL: https://github.com/apache/maven-reporting-impl/pull/25
> 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 that 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17783371#comment-17783371
]
ASF GitHub Bot commented on MSHARED-1326:
-
asfgit closed pull request #19: [MSHARED-1326] Improve (documentation on)
MavenReport interface
URL: https://github.com/apache/maven-reporting-api/pull/19
> 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 that 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17783006#comment-17783006
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on PR #25:
URL:
https://github.com/apache/maven-reporting-impl/pull/25#issuecomment-179374
@kriegaex This is now consistent with m-r-api, please have a final look.
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782996#comment-17782996
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#issuecomment-1793761975
@kriegaex, any further objections before I merge this one?
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782933#comment-17782933
]
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_r1382472623
##
src/main/java/org/apache/maven/reporting/MavenReport.java:
##
@@ -53,10 +53,25 @@ 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 the name of the file
without any extension. The
+ * actual output extension will by added by the sink implementation.
+ *
+ * Note: This method won't be {@code default} anymore when {@link
#getOutputName()} will be removed.
Review Comment:
will --> is
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782930#comment-17782930
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#issuecomment-1793560561
> good clarification
Is the method name change acceptable for you and reasonable?
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782898#comment-17782898
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#issuecomment-1793479323
Now added `#getOutputPath()` and deprecate `#getOutputName()`.
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782890#comment-17782890
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on PR #25:
URL:
https://github.com/apache/maven-reporting-impl/pull/25#issuecomment-1793465845
@elharo, adapted to your comments in the m-r-api. Can you have a look please?
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782370#comment-17782370
]
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_r1380963374
##
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:
@elharo, I agree with you in this case.
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782299#comment-17782299
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on code in PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#discussion_r1380649425
##
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:
@elharo Done, please have another look.
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782295#comment-17782295
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on code in PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#discussion_r1380636744
##
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.
That's exactly what I thought about. The issue is that the plugin does not
know the sink impl therefore it shall not make any assumptions. It could also
be a sink to an output stream of a servlet.
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782289#comment-17782289
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on code in PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#discussion_r1380623760
##
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:
Since all reports are output format agnostic, the output path does not
contain any extension, this is handled by a sink. Basename of the output file.
E.g., index, foo, etc. How would you word 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782288#comment-17782288
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on code in PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#discussion_r1380623760
##
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:
Since all reports are output format agostic, the output path does not
contain any extension, this is handled by a sink. Basename of the output file.
E.g., index, foo, etc. How would you word 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782286#comment-17782286
]
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_r1380616343
##
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.
*
- * @return the output name of this report.
+ * @return the relative path of this report.
Review Comment:
no period
##
src/main/java/org/apache/maven/reporting/MavenReport.java:
##
@@ -84,14 +85,17 @@ public interface MavenReport {
String getDescription(Locale locale);
/**
- * Set a new output directory. Useful for staging.
+ * Set a new shared report output directory. This directory may contain
the output of other
+ * reports as well.
*
- * @param outputDirectory the new output directory
+ * @param outputDirectory the new shared report output directory
*/
void setReportOutputDirectory(File outputDirectory);
/**
- * @return the current report output directory.
+ * Get the shared report output directory.
+ *
+ * @return the current shared report output directory.
Review Comment:
no period
##
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:
still not sure what "basename" means. I guess the point is it's a directory,
not a filename?
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782247#comment-17782247
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#issuecomment-1791230206
@elharo I tried to apply all of your comments. Maybe the method has to
renamed to:
```java
String getOutputPath()
```
since `Name` is misleading...?
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782125#comment-17782125
]
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. Commons 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782028#comment-17782028
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on code in PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#discussion_r1379691836
##
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:
@elharo, it is both. A path to a file. I need to rename the API to satisfy
this. I could do with a default interface method. The current name is just bad.
I am happy to accept any reformulation of the docs which make it better. Should
I raise a PR to rename the method and deprecate it? FWIW, it is not necessarily
a file name because it is free of a format. The plugin impl does not decide
about the format. It is a symbolic name in a virtual FS, so to speak.
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17782026#comment-17782026
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on code in PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#discussion_r1379691836
##
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:
@elharo, it is both. A path to a file. I need to rename the API to satisfy
this. I could do with a default interface method. The current name is just bad.
I am happy to accept any reformulation of the docs which make it better. Should
I raise a PR to rename the method and deprecate 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781970#comment-17781970
]
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_r1379501022
##
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:
Well, I did not write the text, so I am not clinging to it. Maybe I am just
a bit less judgemental or opinionated about it. You are probably right insofar
as the javadoc can do without that part and still be understood.
But just like in requirements engineering it helps the implementor to not
just understand what she needs to deliver and what the acceptance criteria are.
The "(in order) to ..." subclause in a user story adds context and explains the
all-important business value. One could argue: If the story has no value, why
would the creator prioritise it into the sprint in the first place? So it adds
nothing. But wait a minute, does it not? Yes, it does. As an agile coach, since
2006 I have seen literally hundreds of value-less user stories, so it does help
to explain not just the existence of or requirement for something, but also its
purpose or value. Of course, javadoc is not a user story and an apple is not an
orange, but I hope you catch my drift anyway.
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781969#comment-17781969
]
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_r1379501022
##
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:
Well, I did not write the text, so I am not clinging to it. Maybe I am just
a bit less judgemental or opinionated about it. You are probably right insofar
as the javadoc can do without that part and still be understood.
But just like in requirements engineering it helps the implementor to not
just understand what she needs to deliver and what the acceptance criteria are.
The "(in order) to ..." subclause in a user story adds context and explains the
all-important business value. One could argue: If the story has no value, why
would the creator prioritise it into the sprint in the first place? So it adds
nothing. But wait a minute, does it not? Yes, it does. As an agile coach, since
2006 I have seen literally hundreds of value-less user stories, so it does help
to explain not just the existence of or requirement for something, but also its
purpose or 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781968#comment-17781968
]
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_r1379501022
##
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:
Well, I did not write the text, so I am not clinging to it. Maybe I am just
a bit less judgemental or opinionated about it. You are probably right insofar
as the javadoc can do without that part and still be understood.
But just like in requirements engineering it helps the implementor to not
just understand what she needs to deliver and what the acceptance criteria are,
the "(in order) to ..." subclause in a user story adds context and explains the
all-important business value. One could argue: If the story has no value, why
would the creator prioritise it into the sprint in the first place? So it adds
nothing. But wait a minute, does it not? Yes, it does. As an agile coach, since
2006 I have seen literally hundreds of value-less user stories, so it does help
to explain not just the existence of or requirement for something, but also its
purpose or 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781967#comment-17781967
]
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_r1379501022
##
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:
Well, I did not write the text, so I am not clinging to it. Maybe I am just
a bit less judgemental or opinionated about it. You are probably right insofar
as the javadoc can do without that part and still be understood.
But just like in requirements engineering it helps the implementor to not
just understand what she needs to deliver and what the acceptance criteria are,
the "(in order) to ..." subclause in a user story adds context and explains the
all-important business value. One could argue: If the story has no value, why
would the creator prioritise it into the sprint in the first place? So it adds
nothing. But wait a minute, does it not? Yes, it does. As an agile coach, since
2006 I have seen literally hundreds of value-less user stories, so it does
helpto explain not just the existence of or requirement for something, but also
its purpose or 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781965#comment-17781965
]
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 a 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781954#comment-17781954
]
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_r1379471594
##
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:
@elharo, again I ask you to read that from a user's perspective. Users need
more context information than providers and profit from examples and
explanations that a provider might correctly deem redundant. A certain degree
of redundancy or context helps humans to understand things.
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781952#comment-17781952
]
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:
It adds the notion that not necesarily all reports end up directly in that
directory, but that they can also end up in subdirectory. Of cours, 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781950#comment-17781950
]
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_r1379467965
##
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:
@elharo,what it contains (file or subdirectory) depends on whether it is a
single or multi page report. Javadoc would be an example for multi page.
##
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:
@elharo, what it contains (file or subdirectory) depends on whether it is a
single or multi page report. Javadoc would be an example for multi page.
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
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
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781655#comment-17781655
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#issuecomment-1788619992
@elharo As you are a native English speaker and we don't, would you mind to
add your opinion on this?
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17781180#comment-17781180
]
ASF GitHub Bot commented on MSHARED-1326:
-
kriegaex commented on PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#issuecomment-1786288822
> I believe that the last one is logically wrong.
I do not think so, because it dependes on the context and the assumptions
under which users read the documentation. My context is obviously different
from yours, which is why you think it is logically wrong. Maybe it is also a
grammatical question to some degree. I prefer "report base (...) directory" to
"base report (...) directory", as the latter seems to be bad English. It is a
base directory. What kind of base directory? A report base directory, not a
base directory for anything else. Which is why I would order the terms that way.
As for "a lot (of medicine) helps a lot" or combining the terms, making the
result an even more unweildy "shared base report output directory" or "shared
report base output directory" as the lesser evil, I am not sure if that might
not be too subtle for most plugin developers to grasp. In such cases, a little
bit of explanation usually helps, why I usually just expand the description,
maybe even adding an instructive example. Precise and to the point is good, but
sometimes too terse.
I leave the decision up to you, but you asked "WDYT?", so these are my two
cents.
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17780721#comment-17780721
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#issuecomment-1784082469
@kriegaex I'd first to normalize the following:
shared report output directory
vs.
base report output directory
vs.
report base output directory
I believe that the last one is logically wrong. I hink it solely refers to
the report itself and not the rest. It provides false information.
Now we have only two left. What is important to me is that plugin authors
understand that this is not an exclusive directory. Maybe we need to combine
them:
shared base report output directory
WDYT?
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17778497#comment-17778497
]
ASF GitHub Bot commented on MSHARED-1326:
-
kriegaex commented on PR #25:
URL:
https://github.com/apache/maven-reporting-impl/pull/25#issuecomment-1774286815
@michael-o, @hboutemy: See also #26.
> 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-M10,
> maven-reporting-api-4.0.0-M8
>Reporter: Michael Osipov
>Assignee: Michael Osipov
>Priority: Major
> Fix For: maven-reporting-impl-4.0.0-M11,
> maven-reporting-api-4.0.0-M9
>
>
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17778467#comment-17778467
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o opened a new pull request, #25:
URL: https://github.com/apache/maven-reporting-impl/pull/25
(no comment)
> 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-M10,
> maven-reporting-api-4.0.0-M8
>Reporter: Michael Osipov
>Assignee: Michael Osipov
>Priority: Major
> Fix For: maven-reporting-impl-4.0.0-M11,
> maven-reporting-api-4.0.0-M9
>
>
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface/AbstractMavenReport class
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17778468#comment-17778468
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on PR #25:
URL:
https://github.com/apache/maven-reporting-impl/pull/25#issuecomment-1774192022
@kriegaex
> 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-M10,
> maven-reporting-api-4.0.0-M8
>Reporter: Michael Osipov
>Assignee: Michael Osipov
>Priority: Major
> Fix For: maven-reporting-impl-4.0.0-M11,
> maven-reporting-api-4.0.0-M9
>
>
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17778465#comment-17778465
]
Michael Osipov commented on MSHARED-1326:
-
Renaming would be problematic because the same method name is used in Doxia
Sitetools and they would need to be renamed as well for consistency reasons.
> Improve (documentation on) MavenReport interface
>
>
> 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-api-4.0.0-M8
>Reporter: Michael Osipov
>Assignee: Michael Osipov
>Priority: Major
> Fix For: maven-reporting-api-4.0.0-M9
>
>
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17778461#comment-17778461
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o commented on PR #19:
URL:
https://github.com/apache/maven-reporting-api/pull/19#issuecomment-1774184321
@kriegalex
> Improve (documentation on) MavenReport interface
>
>
> 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-api-4.0.0-M8
>Reporter: Michael Osipov
>Assignee: Michael Osipov
>Priority: Major
> Fix For: maven-reporting-api-4.0.0-M9
>
>
> 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)
[jira] [Commented] (MSHARED-1326) Improve (documentation on) MavenReport interface
[
https://issues.apache.org/jira/browse/MSHARED-1326?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17778460#comment-17778460
]
ASF GitHub Bot commented on MSHARED-1326:
-
michael-o opened a new pull request, #19:
URL: https://github.com/apache/maven-reporting-api/pull/19
(no comment)
> Improve (documentation on) MavenReport interface
>
>
> 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-api-4.0.0-M8
>Reporter: Michael Osipov
>Assignee: Michael Osipov
>Priority: Major
> Fix For: maven-reporting-api-4.0.0-M9
>
>
> 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)
