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.)

 customer '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)
======================================================================

N/A

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.
  xxxxx@xxxxx   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.
  xxxxx@xxxxx   1998-12-15

We are not doing this for 1.2.2
  xxxxx@xxxxx   1999-01-25

Should think about more general approaches.
  xxxxx@xxxxx   1999-02-04

Another request for a custom tag, which should be handled generically.
  xxxxx@xxxxx   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.
  xxxxx@xxxxx   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

  stddoclet: Consider making @internal a standard tag

  xxxxx@xxxxx   2002-04-16

I vote for this one. It will be very very useful for the kind of applications
we are working on. Currently I am facing the pbm of generating both internal
and external documentation. Maybe I'll look @ doclets and c if they can help
me.

i sort of did this.  i edited the standard doclet to recognize and handle
an @internal tag, and then if javadoc was run with the -external option,
anything with an @internal tag wouldn't show up.  the catch - it only
works for stuff inside of classes (inner classes, fields, constructors, methods).
it does not work on classes themselves.  why?  because they left the
class tree creation stuff inside the core part of javadoc and made the
class tree very hard to mess with once it was created.

when you look at it, the operation of the @internal tag is identical to
the operation of the @deprecated tag.  by adding additional checks
whenever deprecation checks are performed, this can be achieved
trivially.  of course, they check for deprecated classes inside
ClassTree.java, part of the javadoc api.

so, really easy for them, much messier for us, i say they should
do it

This option should also be able to exclude entire classes or methods from the external javadocs, in effect 
hiding them from end-users.  This goes beyond just hiding parts of comments.

We developed an "external" doclet which will include in the javadocs only those classes with our "external" 
tag or which contain methods marked "external."  

We also developed an "internal" doclet, which displays a big warning next to anything that's marked as 
external.

What's about this tags ??
I think that @exclude and @internal can be replaced by
@category <name> (another proposed tag)
And a -exclude option of javadoc

/**
 * @cat internal
 */
or 
/**
   * @cat test
   *
*/

and 
javadoc -exclude test internal

Please note that doxygen (which can also process Javadoc) 
already recognizes @internal.  It would be really nice if any implementation was comptible with that.

One of my colleages actually seems to think later J2SDKs actually recognize this tag in some form.