[
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)
