Bugzilla (bugzilla.redhat.com) will be under maintenance for infrastructure upgrades and will not be unavailable on July 31st between 12:30 AM - 05:30 AM UTC. We appreciate your understanding and patience. You can follow status.redhat.com for details.
Bug 880359 - JavaDoc used for Remote API is inconsistent with API
Summary: JavaDoc used for Remote API is inconsistent with API
Alias: None
Product: JBoss Operations Network
Classification: JBoss
Component: Productization
Version: JON 3.1.1
Hardware: All
OS: All
Target Milestone: ER05
: JON 3.3.0
Assignee: Heiko W. Rupp
QA Contact: Mike Foley
Depends On:
Blocks: 991510 1032556
TreeView+ depends on / blocked
Reported: 2012-11-26 19:49 UTC by Larry O'Leary
Modified: 2015-08-10 01:22 UTC (History)
6 users (show)

Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Clone Of:
Last Closed: 2014-12-11 14:05:09 UTC
Type: Task

Attachments (Terms of Use)

System ID Private Priority Status Summary Last Updated
Red Hat Bugzilla 749368 0 unspecified CLOSED add @since Javadoc tags to our public APIs (agent plugin API and server remote API) 2021-02-22 00:41:40 UTC

Internal Links: 749368

Description Larry O'Leary 2012-11-26 19:49:20 UTC
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.

Comment 8 Charles Crouch 2013-02-26 16:11:51 UTC
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

Comment 9 Charles Crouch 2013-02-26 16:39:31 UTC
Didn't mean to change the priority. From the gss/dev call medium is the correct severity.

Comment 10 Jay Shaughnessy 2013-10-18 13:21:53 UTC
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...

Comment 11 Jay Shaughnessy 2014-04-22 15:59:06 UTC
master commit 44960d453e647b2b47291d84a4ca324de1a2db56
Author: Jay Shaughnessy <jshaughn@redhat.com>
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.

Comment 12 Simeon Pinder 2014-07-31 15:52:36 UTC
Moving to ON_QA as available to test with brew build of DR01: https://brewweb.devel.redhat.com//buildinfo?buildID=373993

Comment 13 Mike Foley 2014-07-31 22:17:31 UTC
failed qe

references jon 3.2 doc 

Comment 14 Jay Shaughnessy 2014-08-01 13:49:25 UTC
Reviewd and Merged PR. Master Commits:

commit 8576ff2cf9d7e82e6a2ba6422763cb81d17839cf
Merge: 120bf6e d3d57a4
Author: jshaughn <jshaughn@redhat.com>
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@redhat.com>
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

Comment 15 Jay Shaughnessy 2014-08-01 13:50:03 UTC
Argh - ignore Comment 14, wrong BZ

Comment 16 Jay Shaughnessy 2014-08-01 15:22:34 UTC
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...

Comment 17 Jay Shaughnessy 2014-09-09 15:35:58 UTC
Assigning this to Heiko as I think he has an idea about how the javadoc is generated.

Comment 19 Heiko W. Rupp 2014-09-25 19:19:53 UTC
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)

Comment 21 Simeon Pinder 2014-09-29 08:12:57 UTC
Moving into ER05 as didn't make the ER04 cut.

Comment 22 Libor Zoubek 2014-10-10 14:09:57 UTC
This has been fixed within Bug 1032556

Comment 24 Simeon Pinder 2014-10-21 20:24:37 UTC
Moving to ON_QA as available to test with the latest brew build:

Note You need to log in before you can comment on or make changes to this bug.