Name: rmT116609 Date: 11/19/2003


A DESCRIPTION OF THE PROBLEM :
Please also see bug 4933335 for related information.

I'd like you to consider reversing a design decision related to JAVADoc. I'm submitting this as a bug because it really is, in that this decision is causing JAVADoc to incorrectly portray the multiple-inheritance interface structure we're using.

In brief, when the same method is specified in several interfaces that I either extend (interface) or implement (class), JAVADoc should tell me everywhere this method is specified. Right now it (evidently) arbitrarily picks one of the instances. Besides being inaccurate, it creates a false sense of security among developers who may inherit this code from me some day.
I say it's a false sense of security because the JAVADoc will (mis)lead them to believe that they know what they're impacting by changing some data, but they really don't (not even close in this case).

I would ask that JAVADoc always accurately and completely portray and communicate the inheritance structures that can be created using JAVA interfaces and classes. This should include multiple levels of inheritance.

getCreateDate
public Date getCreateDate()
  Description copied from interface: IProductSpecification

Gets the date this product was created.

Specified by:

getCreateDate in interface IProductSpecification

Returns:

Date this product was created.

 
  From a correctness point of view, it's really not (strictly) correct to say that the method is specified (just) by IProductSpecification. It's really specified by many

Interfaces. From a practical point of view, it's misleading because it gives a false impression that this is the only place this information is used. This can be dangerous if someone uses the setter for this and ends up changing data in places they never knew would be impacted. It's unfair to the users of any such API because even if they "do the right thing' and read the Javadoc, they'll still get into trouble. It can also lead to lots of support calls and questions (one of the things Javadoc should help to reduce) because a programmer may not be able to determine (without consultation) how to set the (I know I have a get example here, but there is a setter for every getter) create date anywhere but in a product.

 

This inaccurate and incorrect portrayal of the inheritance structure diminishes the value and effectiveness of Javadoc. One of the many benefits of object oriented programming is the ability to create interfaces and contracts to (hopefully tightly) specify the relationship between software objects. One important piece of this is the ability to accurately document the interfaces and contracts so that the programmer fulfulling a contract (and implementing the associated interfaces) can easily get access to the terms of the contract. This includes being able to readily see what they're doing when they set a particular attribute (such as create date).

 

For a personal example, each of the I*Specification methods (including IProductSpecification) pertains to a different table in our database. If you link to (as of today) the I*Specification, you'll see exactly which data attributes (table and column) are being selected, inserted, or updated. That's what the database.Table and database.Attribute tags are for.

 

Since Javadoc doesn't show all the interfaces (it should, at least in Specified by) it's difficult to know up-front which interfaces to look at to get a complete picture of what database attributes will be affected by changing the value of this field (such as create date).

 

If the Specified by section (correctly) showed all of the interfaces this method is specified by, it would be easy and fast to determine what's being impacted by setting a variable. As things stand now, it's only possible using one's own memory or doing an exhaustive search of each I*Specification interfaces. In this case Javadoc doesn't add that much value, but it should.

 

Ideally, there should also be a way to do this in IInterfaceSpecification. I shouldn't have to create an implementation of this specification (interface) to effectively document it.

 
I now have to do some refactoring of my interface structure to accommodate additional business needs/exceptions. I have to search through my interfaces to find all instances of the methods I need to split out, since JAVADoc doesn't tell me everywhere this method is defined. This would be even worse for us if I had turned this over to a maintainer who wasn't as familiar with the structure as I am.



STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
Create JAVADoc on my inheritance structure.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
Correct and accurate communication of the inheritance structure. Add value to the process by serving as a reliable/believable reference for other developers who must use this API.
ACTUAL -
Incomplete and misleading results as specified above.

ERROR MESSAGES/STACK TRACES THAT OCCUR :
None. This creates a false sense of security, because the results aren't right.

REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
Previously submitted with 4933335
---------- END SOURCE ----------

CUSTOMER SUBMITTED WORKAROUND :
My own memory! :-)
(Incident Review ID: 223117)
======================================================================