JDK-4102647 : stddoclet: Consider making @internal a standard tag
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.2.0
  • Priority: P4
  • Status: Resolved
  • Resolution: Duplicate
  • OS: generic
  • CPU: generic
  • Submitted: 1998-01-08
  • Updated: 2024-04-12
  • Resolved: 2016-10-12
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
tbdResolved
Related Reports
Duplicate :  
JDK-8073100 - [javadoc] Provide an ability to suppress document generation for specific elements.
Relates :  
JDK-4359470 - javadoc tool: Modify Comment.java for easy writing of custom tags
Relates :  
JDK-4282805 - stddoclet API: Add tag listener interface for custom tags
Description
Name: dgC58589			Date: 01/08/98

It would be terrifically handy to use doc comments not only to produce API documentation, but also to maintain internal design documentation inline (so it is under revision control, and would have a shot at getting updated when the code is changed).  Also, one might want to maintain things like TODO lists in API documentation that is only seen in house.

It would be helpful to have a scheme to allow tagged comments (or parts of tagged comments) to only be processed if some "internal" option is given on the javadoc command line.  This could be implemented with a new @internal tag, or could be linked to the current idea of privacy.  (A doc comment on a public method that included a @private tag would not be processed unless the "-private" option is used on the javadoc command line.)

Microsoft's autoduck has some ability to tag comments as "internal only"  We have used that to integrate our design documentation with our external documentation (and the source code).

Thanks.

David Dhuyvetter
(Review ID: 22867)
======================================================================
Comments
JDK-8073100
12-10-2016
See also @treatAsPrivate
12-02-2016
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: dragon
08-07-2004
EVALUATION We need to look deeper into this before finalizing something in the standard doclet. Won't do for 1.2. Developers can write their own doclets for now. doug.kramer@Eng 1998-04-03 This ties in with bug 4058216 about @hide/@exclude/@ignore, and request 4074234 -recurse, so we should consider them at the same time. doug.kramer@Eng 1998-12-15 We are not doing this for 1.2.2 atul.dambalkar@eng 1999-01-25 Should think about more general approaches. robert.field@Eng 1999-02-04 Another request for a custom tag, which should be handled generically. doug.kramer@Eng 2001-02-27 This request is to to "allow tagged comments (or parts of tagged comments) to only be processed if some "internal" option is given on the javadoc command line". This is resolved by implementing custom tags, RFE 4282805. doug.kramer@Eng 2001-06-27 It is worth considering whether @internal should be made a standard tag. Changed synopsis from: stddoclet?: Should support internal documentation, such as @internal to: stddoclet: Consider making @internal a standard tag ###@###.### 2002-04-16
16-04-2002