[Fortress] Java 8, Javadoc and build...

[Emmanuel Lécharny <el...@gmail.com>]

Hi guys,

I have downloaded the latest version of the 4 fortress projects, and
tried to build them with Java 8. It's a pain...

Again, the javadoc lint that those idiots at oracle have decided to
include in Java 8 make it a real pain to get a build that works if the
Javadocs are not perfect. That's ok  for the missing @param or @return,
but when it comes to HTML, frankly, it's totally retarded.

There are two options here :
- first, dismiss the Java 8 lint by adding this property in Maven pom.xml :

...
    <properties>
      <additionalparam>-Xdoclint:none</additionalparam>
...

- second, fix the errors.

Being a bit anal, I'm currently trying to go through option 2, for the
sake of seeing what kind of pain it could be. Here is an example of
'wrong' HTML, per Java 8 :

    /**
     * This method performs an update on User entity in directory. 
Prior to making this call the entity must exist in
     * directory.
     * <h4>required parameters</h4>
     * <ul>
     *   <li>{@link FortRequest#entity} - contains a reference to {@link
org.apache.directory.fortress.core.model.User} object</li>
     *   <h5>User required parameters</h5>
     *   <ul>
     *     <li>{@link
org.apache.directory.fortress.core.model.User#userId} - maps to
INetOrgPerson uid</li>
     *   </ul>
     *   <h5>User optional parameters</h5>
     *   <ul>
     *     <li>{@link
org.apache.directory.fortress.core.model.User#password} - used to
authenticate the User</li>
     *     <li>{@link org.apache.directory.fortress.core.model.User#ou}
- contains the name of an already existing User OU node</li>
     *     <li>{@link
org.apache.directory.fortress.core.model.User#pwPolicy} - contains the
name of an already existing OpenLDAP password policy node</li>
     *     <li>{@link org.apache.directory.fortress.core.model.User#cn}
- maps to INetOrgPerson common name attribute</li>
...
     *   </ul>
     * </ul>
     * <h4>optional parameters</h4>
     * <ul>
     *   <li>{@link FortRequest#session} - contains a reference to
administrative session and if included service will enforce ARBAC
constraints</li>
     * </ul>
     *
     * @param request contains a reference to {@code FortRequest}
     * @return reference to {@code FortResponse}
     */
    FortResponse updateUser( FortRequest request );

and here is the list of totally morronic excuses for Java 8 lint to
reject this Javadoc :

[ERROR]
/Users/elecharny/apacheds/fortress/enmasse/src/main/java/org/apache/directory/fortress/rest/FortressService.java:227:
error: header used out of sequence: <H4>
[ERROR] * <h4>required parameters</h4>
[ERROR] ^
[ERROR]
/Users/elecharny/apacheds/fortress/enmasse/src/main/java/org/apache/directory/fortress/rest/FortressService.java:230:
error: tag not allowed here: <h5>
[ERROR] *   <h5>User required parameters</h5>
[ERROR] ^
[ERROR]
/Users/elecharny/apacheds/fortress/enmasse/src/main/java/org/apache/directory/fortress/rest/FortressService.java:231:
error: tag not allowed here: <ul>
[ERROR] *   <ul>
[ERROR] ^
[ERROR]
/Users/elecharny/apacheds/fortress/enmasse/src/main/java/org/apache/directory/fortress/rest/FortressService.java:234:
error: tag not allowed here: <h5>
[ERROR] *   <h5>User optional parameters</h5>
[ERROR] ^
[ERROR]
/Users/elecharny/apacheds/fortress/enmasse/src/main/java/org/apache/directory/fortress/rest/FortressService.java:235:
error: tag not allowed here: <ul>
[ERROR] *   <ul>
[ERROR] ^


Bottom line, fixing them is just a matter of changing the Javadoc to :

    /**
     * This method performs an update on User entity in directory. 
Prior to making this call the entity must exist in
     * directory.
     * <h3></h3>
     * <h4>required parameters</h4>
     * <ul>
     *   <li>{@link FortRequest#entity} - contains a reference to {@link
org.apache.directory.fortress.core.model.User} object</li>
     * </ul>
     * <ul style="list-style-type:none">
     *   <li>
     *     <ul style="list-style-type:none">
     *       <li>
     *         <h5>User required parameters</h5>
     *         <ul>
     *           <li>{@link
org.apache.directory.fortress.core.model.User#userId} - maps to
INetOrgPerson uid</li>
     *         </ul>
     *       </li>
     *       <li>
     *         <h5>User optional parameters</h5>
     *         <ul>
     *           <li>{@link
org.apache.directory.fortress.core.model.User#password} - used to
authenticate the User</li>
     *           <li>{@link
org.apache.directory.fortress.core.model.User#ou} - contains the name of
an already existing User OU node</li>
     *           <li>{@link
org.apache.directory.fortress.core.model.User#pwPolicy} - contains the
name of an already existing OpenLDAP password policy node</li>
...
     *         </ul>
     *       </li>
     *     </ul>
     *   </li>
     * </ul>
     * <h4>optional parameters</h4>
     * <ul>
     *   <li>{@link FortRequest#session} - contains a reference to
administrative session and if included service will enforce ARBAC
constraints</li>
     * </ul>
     *
     * @param request contains a reference to {@code FortRequest}
     * @return reference to {@code FortResponse}
     */
    FortResponse updateUser( FortRequest request );


Note (and appreciate !!!) the empty <h3> tag (just because Java 8 lint
code does not like non-sequenced <H> tags...). Don't even think that
<h3/> will make it, you'll get the infamous "error: self-closing element
not allowed". And also the whole vomit of extra <UL> and <Li>...


Just one word : if you are working at Oracle and on the Java language
team, YOU ARE IDIOTS.