JDK-4085609 : stddoclet: Need to document properties apart from their getter/setters
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.2.0
  • Priority: P4
  • Status: Closed
  • Resolution: Duplicate
  • OS: solaris_2.6
  • CPU: generic
  • Submitted: 1997-10-11
  • Updated: 2024-10-09
  • Resolved: 2013-12-12
Related Reports
Duplicate :  
JDK-4085608 - stddoclet: Add member categories (@category) so parameter can link to constants
Description
Categories are needed for properties.

Ex: setColor(), getColor() methods define the property "Color".
It is the Color property that needs explanation, not the individual methods.

   PROPERTY
      getProperty
      setProperty
      isProperty
Sometimes other collections of methods belong together in a single
category, as well.

Might be handled like categories for static fields (bug 4085608)
Comments
This is a duplicate of 4085608.
12-12-2013
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: dragon
14-06-2004
EVALUATION Our current convention (not widely used) is that the description of the property should go with the setter, not the getter. We might want to use @pair instead of @category, because @category might be better used to group related methods not in setter/getter pairs but by how they are categorized in the Chan/Lee books, such as "Format methods" or "String Handling Methods" and so forth. doug.kramer@Eng 1998-03-17 I don't think this would be solved by categories (the issues are orthogonal, since categories are not concerned with getter/setter pairs -- "read methods" "write methods" are categories). Therefore, changed synopsis from "Categories needed for related methods" to "Need to document properties apart from their getter/setters". For one, it would be nice to be able to look up the property name in the javadoc-generated index. doug.kramer@Eng 1998-04-03 This was vote for overwhelmingly at the 2001 Javadoc BoF. Somewhere between 60% (Doug's guess) and 90% (Neal's guess) voted for this. Therefore, raising the priority from 5 to 4. doug.kramer@Eng 2001-06-29 This request has been denied by the Tiger planning committee, with a low rating of 8, which means not clear that this is worth doing. (1 is top rating) ###@###.### 2002-08-09 I believe if we want to pursue this, we need more feedback from users as to a few facts: 1) Do they want the property name to appear *instead of* the setters and getter methods? 2) Or do they merely want a property summary table (as in Dave Brownell's) example) and still document the setter and getter methods as always? 3) Do they want an option to choose between HTML pages that display property names only vs. normal javadoc setter and getter methods? This might satisfy bean users without disturbing others. 4) What's the benefit in looking up by property name? Are property names what appear in beans applications? ###@###.### 2002-08-09 > Scott, do you see value in the proposed RFE? I do know the beans architecture. I'm not entirely clear on what this RFE is proposing. Having javadoc produce a chart showing bean properties could be handy, but I wouldn't do it in place of the standard method documentation that we already have. Also, I'm not sure how method information described by a BeanInfo fits into this. In such cases it's possible that the read/write methods won't begin with get/set. The developer can use a PropertyDescriptor to provide unconventional names for the read/write methods. ###@###.### (pasted by ###@###.###)
11-06-2004