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