Hi guys,
Recently, when I tried to deploy eagle 0.5.0-incubating-snapshot artifacts
based on develop branch, the entire build flow was broken by lots of faulty
javadoc, which are classified in following aspects. I'll try to erase
illegal/meaningless javadoc, and please PAY ATTENTION to your contribution
and avoid checking-in such inappropriate javadoc:
1. Illegal character found, e.g. "<", or ">". Except for recognized html
tags, such as "<pre></pre>", "<b></b>", etc., other angle brackets should
be replaced with entities, say, "<" should be "<", and ">" should be
">".
2. Many "<p>" and "</p>" found in apache license comment, enclosing the
license url. This kind of "p" tag is not allowed by javadoc, and actually,
it's useless to be placed in the license comment either. Next time you
create a new java file, please refer to another existing java file and
copy+paste the correct license comment to the head of your new file, and
make sure it does contain the "<p></p>" pair around the license url.
3. Many meaningless parameters and javadoc blocks found in files. This
issue could be more descriptive with a sample, see below javadoc fragment
that appears many times in eagle project on develop branch:
/**
*
* @param arg1
* @param arg2
* @return
*/
This is a sample for rather meaningless javadoc. First, if there is no
description, why shall we add this javadoc? Seconds, if we don't add
description for arguments, who can know what to pass to the methods exactly
by reading the javadoc? Third, if we don't add description for return
value, how can customers understand the returning stuff by reading the
javadoc? As a whole, such javadoc should be erased because we are not
adding javadoc just for "adding", but for users or even code writers
themselves to understand code more clearly.
4. Wrong upper case javadoc tag found. E.g. "@since" should be written in
all lowercase, but found as "@Since", which make the javadoc generator
complain with errors.
So far, I've deployed eagle 0.5.0-incubating-snapshot to apache maven
snapshot repository (
https://repository.apache.org/content/repositories/snapshots/org/apache/eagle/).
It currently doesn't include javadoc jars because there were too many
javadoc error occurring while I was building the artifacts. When I erased
incorrect ones in a sub model, that model ran pass and the next model in
building chain raised up to complain. Therefore, it may cost me more time
to erase all the faulty javadoc until all models are built successfully.
Thank you for your understanding and cooperation.
Michael
