Description of problem: The JavaDoc has not been kept in sync with the API. For example: PackageVersion org.rhq.enterprise.server.content.ContentManagerRemote.createPackageVersionWithDisplayVersion(Subject subject, String packageName, int packageTypeId, String version, String displayVersion, Integer architectureId, byte[] packageBytes) Defines the following JavaDoc parameters: @param subject The logged in subject @param packageName parent package name; uniquely identifies the package under which this version goes @param packageTypeId identifies the type of package in case the general package needs to be created @param version identifies the version to be create @param architectureId architecture of the newly created package version. If null then no architecture restriction. But, as we can see from the method signature, the parameters displayVersion and packageBytes are missing. Another one: PackageVersion org.rhq.enterprise.server.content.ContentManagerRemote.createPackageVersion(Subject subject, String packageName, int packageTypeId, String version, Integer architectureId, byte[] packageBytes) Is missing packageBytes parameter. Perhaps we need to perform JavaDoc compliance validation to ensure all API methods have appropriate JavaDoc tags along with descriptions. I also see many deprecation notices without explanation of deprecation along with new methods that do not indicate when they were introduced.
The effort on this BZ is for engineering to investigating a build tool which can prevent such occurrences from happening again, e.g. when the api changes the javadoc must change to
Didn't mean to change the priority. From the gss/dev call medium is the correct severity.
Eclipse has javadoc validation stuff under preferences->java->compile->javadoc. I turned on some validation and it does catch the issues larry points out above, and more. I'll make a sweep of the remote api...
master commit 44960d453e647b2b47291d84a4ca324de1a2db56 Author: Jay Shaughnessy <jshaughn> Date: Tue Apr 22 11:57:09 2014 -0400 I made another pass at the remote API jdoc, ensuring that all methods have at least minimal jdoc with the correct @param, @return, @throws, @deprecated and @since (starting with RHQ 4.5) annotations.
Moving to ON_QA as available to test with brew build of DR01: https://brewweb.devel.redhat.com//buildinfo?buildID=373993
failed qe references jon 3.2 doc http://hostname:7080/coregui/#Help/Section1/Section1Item7
Reviewd and Merged PR. Master Commits: commit 8576ff2cf9d7e82e6a2ba6422763cb81d17839cf Merge: 120bf6e d3d57a4 Author: jshaughn <jshaughn> Date: Thu Jul 31 17:14:52 2014 -0400 Merge pull request #102 from rhq-project/bug/1124614 BZ 1124614 - auto-update agent if its version doesn't match the latest agent version commit d3d57a45377d007ccd10febddf1e093330e270f8 Author: John Mazzitelli <mazz> Date: Thu Jul 31 14:39:51 2014 -0400 BZ 1124614 - if an agent's auto-update is enabled, then always update itself if its version is not the same as the latest agent version of the agent distro in the server
Argh - ignore Comment 14, wrong BZ
This is a bit different, now the complaint is that Help->API Javadoc in the GUI is not linking to the newest API doco. That will need to be generated and added to the JON documentation. And then we can update the link. I'm not sure what that process is. I'm going to flag Heiko for what needs to be done...
Assigning this to Heiko as I think he has an idea about how the javadoc is generated.
We should also * implement a build job like the api-checker that fails the build when javadoc is missing in the remote api and dependent classes (mostly core/domain) * move in the long run all remote-apis related classes into their own package (and make sure no internal impl detail or local interfaces are leaking)
Moving into ER05 as didn't make the ER04 cut.
This has been fixed within Bug 1032556
Moving to ON_QA as available to test with the latest brew build: https://brewweb.devel.redhat.com//buildinfo?buildID=394734