Hello all
I'm starting to work on a prototype using the new build <Source> element
(a proposal for a unified replacement for <sourceDirectory>,
<testDirectory>, <resources>, etc.) proposed in a previous discussion on
this mailing list. For starting, I'm searching for usages of
<sourceDirectory> in Maven source code and I try to add codes doing
something equivalent for <Source>.
However, a difficulty I'm facing is the quasi-absence of documentation
in Maven source code. The vast majority of code has no comment at all. I
miss in particular comments that would explain *why* a code is designed
the way it is. One example I have met just now
(DefaultModelPathTranslator at line 118):
private String alignToBaseDirectory(String path, Path basedir) {
String newPath = pathTranslator.alignToBaseDirectory(path, basedir);
return Objects.equals(path, newPath) ? null : newPath;
}
This method is invoked for all well-known paths of the <build> element:
<sourceDirectory>, <testDirectory>, <outputDirectory>, etc. But why this
method sets the directory to null when there is no change? Is it a bug?
Is it intended? Without comment explaining the intend, it is hard to
guess. It is especially puzzling because just above that method, there
is another method doing the exact opposite (returning the existing
object when there is no change).
For now, I will design the <Source> handling with the assumption that
above null return value is a bug. But without documentation explaining
method contract, there is a risk that I make wrong choices (the above
case is just one example among many).
Martin
