Good reminding. @Contributors, not only about java docs, pls. make sure all the code style matches the checkstyle, currently I just keep the checkstyle as WARNING as we still have lots of style warning to clean, in future we should throw ERROR if any check-style doesn't match. Pls. start to spend sometime cleaning the checkstyle warning in your code right now.
- Hao On Wed, Aug 24, 2016 at 3:04 PM, Michael Wu <[email protected]> wrote: > 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 >
