search

oasp / oasp4j

The Open Application Standard Platform for Java
Apache License 2.0
60 stars 303 forks source link

#479: generate service documentation in maven site #499

Closed hohwille closed 8 years ago

hohwille commented 8 years ago

As cure for #479 we now have service documentation in maven site with this PR. Locally tested with mvn site (see reports in sample core)...

jomora commented 8 years ago

@hohwille I adhered to your hint of setting JDK 7 to make the mvn site command work, but unfortunately it doesn't. The maven-javadoc-plugin gives the following error:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.4:site (default-site) on project oasp4j: Error generating maven-javadoc-plugin:2.9.1:aggregate:
[ERROR] Exit code: 1 - javadoc: error - invalid flag: -Xdoclint:none
[ERROR]
[ERROR] Command line was: "C:\Program Files\Java\jdk1.7.0_80\jre\..\bin\javadoc.exe" @options @packages
[ERROR]

I spent some time on this and I just couldn't figure out a solution.

@all Does anyone else face this problem?

FYI: I checked out the PR with the following git command:

git fetch <remote> pull/499/head:myLocalBranch`  #where <remote> == "upstream" in my case.
git checkout myLocalBranch

Does anyone find a problem in this command? I can't and I'm pretty sure it works as intended.

jomora commented 8 years ago

Using JDK 8 resolves the doclint error, but new problem have arisen.

The following errors come up due to broken links and typos in JavaDoc:

 Failed to execute goal org.apache.maven.plugins:maven-site-plugin:3.4:site (default-site) on project oasp4j: Error generating maven-javadoc-plugin:2.9.1:aggregate:
[ERROR] Exit code: 1 - C:\OaspIDE\ide\workspaces\main\oasp4j\modules\security\src\main\java\io\oasp\module\security\common\api\accesscontrol\AccessControl.java:31: warning - Tag @see: can't find getName() in io.oasp.module.security.common.api.accesscontrol.AccessControl
[ERROR] C:\OaspIDE\ide\workspaces\main\oasp4j\modules\basic\src\main\java\io\oasp\module\basic\common\api\to\AbstractEto.java:17: warning - Tag @link: reference not found: net.sf.mmm.util.transferobject.api package JavaDoc
[ERROR] C:\OaspIDE\ide\workspaces\main\oasp4j\modules\jpa\src\main\java\io\oasp\module\jpa\common\api\to\SearchCriteriaTo.java:25: warning - Tag @see: reference not found: getSearchTimeout
[ERROR] C:\OaspIDE\ide\workspaces\main\oasp4j\modules\jpa\src\main\java\io\oasp\module\jpa\dataaccess\base\AbstractGenericDao.java:232: warning - @query is an unknown tag.
[ERROR] C:\OaspIDE\ide\workspaces\main\oasp4j\modules\jpa\src\main\java\io\oasp\module\jpa\dataaccess\base\AbstractGenericDao.java:232: warning - @query is an unknown tag.
[ERROR] C:\OaspIDE\ide\workspaces\main\oasp4j\modules\jpa-envers\src\main\java\io\oasp\module\jpa\dataaccess\base\AbstractGenericRevisionedDao.java:27: warning - Tag @link: reference not found: org.hibernate.envers
[ERROR] Hibernate-Envers
[ERROR] javadoc: error - com.sun.tools.doclets.internal.toolkit.util.DocletAbortException: com.sun.tools.javac.code.Symbol$CompletionFailure: class file for javax.interceptor.InterceptorBinding not found
[ERROR]
[ERROR] Command line was: C:\Muenchen\PNR\IDE\software\java\jre\..\bin\javadoc.exe @options @packages
[ERROR]
[ERROR] Refer to the generated Javadoc files in 'C:\OaspIDE\ide\workspaces\main\oasp4j\target\site\apidocs' dir.
[ERROR] -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException

I was not able to resolve the errors where "@link" references a Java package, but does not work. However, it also does not work in Eclipse directly.

Does anyone know how to properly reference Java packages in JavaDoc?

EDIT: Thanks @HerdplattenToni for your help!!! However, the doclint problems vanished when switching to JDK 8 again.

jomora commented 8 years ago

It is important to notice that exceptions regarding com.gemstone.gemfire:gemfire:pom:8.1.0 are expected (although not desired) behaviour.

jomora commented 8 years ago

Please, be aware that site generation still has problems as mention in #506. A fix will be provided in another PR. However, these problems are not of concern in this PR.