javadoc is including my generated _Stub and _Skel classes in its output, which is nonsensical and complicating.  These are generated classes -- either they are not being marked as such, or javadoc is not ignoring generated classes.

  xxxxx@xxxxx   wrote:
> Ken filed that bug in that interest of external, non-J2SE uses
> of javadoc, in which there might very well be a different definition of
> what are the elements of a package that are relevant to specification
> (or other uses)-- i.e. in which there is not necessarily a one-to-one
> mapping between elements of specification and the Java-level public
> APIs of a package (like J2SE).  Ken wasn't claiming that his desire to
> exclude generated RMI _Stub classes applied to J2SE itself.

===========
This bug has been fixed.  The -include and -exclude options have been added to the standard doclet.  If "-exclude foo1:foo2" is used, all members, classes and packages with @docset foo1 and/or @docset foo2 will be excluded from the standard doclet output.  If "-include foo1:foo2" is used, ONLY members, classes and packages with @docset foo1 and/or @docset foo2 will be included in the output.

  xxxxx@xxxxx   2001-05-14

NOTE: this bug fix is being withdrawn from Merlin.  Please DO NOT document
this feature for Merlin.

  xxxxx@xxxxx   2001-08-13This is a feature to enable developers to skip classes and packages when 
running javadoc.

People might want gradations of exclusion --
they might want to exclude a class for expert developers (service providers),
but include it for normal developers.  If the tag can be named, it would be
possible to include all classes with a certain name:  "@exclude licensee"
would be excluded by default (with or without the name "licensee",
but could be overridden with "javadoc -include licensee".

This should work at the member level, class level and package level.

One developer suggests @publicAPI rather than @exclude.  @publicAPI
would mark API that should be documented for external use (and in 
his case, not be obfuscated).   -public would be relegated to 
internal documentation only.  Reasons:

  1) The methods, fields and classes that are API public are most
     likely to have doc comments already,  the @exclude would need
     to be added to elements devoid of doc comments.
  2) The API public elements are usually fewer in number than 
     the 'public' access symbols that would require '@exclude'

--------------------------------------------------------------
From another submitter:

One of the reasons we find it useful to exclude a class is that we have 
a class in the package that can be used by support in the field but is 
of no use to the programmer using the public api of the product in that 
same package.

If we move this class to a sub package, it is now outside the package it wants
to be a part of for package private functionality.

To exclude public classes, pass in only the source filenames for the classes you want to include.  For example, if you have classes package.A, package.B and package.C, you can exclude C by passing in only classes A and B:

  javadoc -d doc package/A.html package/B.html

An alternative is to use yDoc Doclet, described at:
http://java.sun.com/j2se/javadoc/faq/index.html#ydoc

By adding @y.exclude, you can exclude classes, fields, and methods.

  xxxxx@xxxxx   2003-10-08

Javadoc currently does not ignore classes except by access
(public, private, etc).  That is, it does not ignore generated 
classes.

I believe javadoc does not know if a class is generated or not
(other than by a filename).  Feedback I've gotten from Josh 
(from TRC) is that there should be something explicit other 
than the filename to tell javadoc to skip the class, rather 
than having it rely the fact that it's generated.  Ken, is 
there a way for the RMI compiler to mark a class as generated?

  xxxxx@xxxxx   1998-04-03


There is a synthesized bit for the class but it is not currently
set by the compiler.

I don't know from RMI but, I assume it isn't the java compiler that 
generates stubs and skeletons anyhow, but rather an RMI compiler.

-Robert
1998-04-06

> Doug said:
> Is there a way for the RMI compiler to  mark a class as generated?
> We're looking for a suggested way to fix this that doesn't involve
> heuristics.

Well, you already have some heuristics, right?  How else do you map
inner class names to use "." instead of "$"?  (And what do you do with
user classes that happen to use "$" in them?)

I *thought* there was a flag in the class file that marked an identifier
as being a generated one.  But I can't find it quickly in my VM spec,
and for all I know it post-dates the spec I have.  Maybe Tim Lindholm
would know.

Ken   1998-04-06

-----
BTW, if we decide to add a tag, I prefer "@hide".  "@skip" to me implies
sequencing in a way that seems inappropriate.

-Robert

-----


Hi Doug,

If there was a javadoc tag like "@ignore", rmic could add that tag
to the javadoc comment for the classes it generates.  Then javadoc
could skip files with the "@ignore" tag.

$.02,

-- Ann

------
From dkramer Tue Apr  7 10:49:22 1998

I submitted this idea to the Technical Review Committee on Feb 17:

  Problem: Javadoc mistakenly documents peer classes, java.text resource 
           classes, and generated classes such as RMI stubs and skeletons.  
           The are all classes that must be public, but are not part of 
           the API spec. 
 Solution: Workaround is to omit those classes from the javadoc command.  
           Better solution might be to add an @skip or @exclude tag for 
           classes. 
Requestor: Ken Arnold plus other developers

The TRC said this problem should be resolved by modifying the makefile.
(This is part of RFE #4113722)  Now it's clear that modifying the
make file would solve the peer and resource class problem, but not 
the RMI stubs and skeletons problem.  At the time we didn't consider
this case as you are clearly stating.

Josh, as a TRC member, is this worth re-considering adding a tag
to exclude classes from javadoc, for generated classes that do not
appear in the make file?

-Doug

-----

I think that it is worth considering adding a tag to supress JavaDoc 
generation.
				Josh
-----
Therefore, it appears we should consider @hide as the recommended fix.  
Won't add it in the standard doclet for 1.2 since we're feature-frozen, but
can do it in a custom doclet.

A question I have is whether we also need to implement an override for @hide
for internal documentation when people might want to actually document
API marked with @hide.
  xxxxx@xxxxx   1998-04-13

I think @hide is not as good a name as @ignore or @exclude, because 
someday when we have customizable interfaces to a javadoc-generated 
database, the term "Hide" will mean to not display it, even though
javadoc has generated it.  

Also, you can bet that people will want gradations of exclusion -- 
they might want to exclude a class for outside developers, but include 
it in internal docs.  If the tag can be named, it would be possible
to include all classes with a certain name:  "@exclude licensee"
would be excluded by default (with or without the name "licensee", 
but could be overridden with "javadoc -include licensee".

Or should it work the other way around:  you would exclude marked 
classes by matching the name: "javadoc -exclude licensee"
and could include them by default?

Or should -exclude take a package or class name, so you could
combine it with -recurse:   javadoc -recurse package1 -exclude package2
This should work at the member level, class level or package level.
  xxxxx@xxxxx   1998-12-15

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

At the Javadoc BOF at JavaOne 1999, this feature voted 3rd place (13 votes) as:
@exclude tag to hide packages, classes, or members.  Important to be able to override this on the command line for internal documentation.
  xxxxx@xxxxx   1999-10-20

We now do this for the MIF doclet.  In the long run, I don't know if 
this is best done in the javadoc tool (to help reduce memory requirements?)
or in the standard doclet.  I've assigned it to stddoclet for now. 
  xxxxx@xxxxx   2000-12-06

------------------------------------------------------------
People say they want "@hide" but user feedback is never to be taken at face 
value.  What they are saying is they want a way to hide stuff, and @hide is the 
obvious solution.  It also happens to be the wrong one.  We can do better, and 
people will like categorization, too -- it solves their immediate problem and a 
bunch of others they haven't had yet, but many will.  Yes, it will take more 
thought to get it right, but it will be better.

@hide gives me a binary choice that the writer of the doc must make for all time 
(unless you edit the file, of course).  Categorization gives the generator of 
the doc the control, and leaves the doc writer to decide what kind of entity is being documented, something they understand better.

Actual example: with Jini we give away all the source.  In com.sun.jini packages 
there are two kinds of sources: internal hacks and "classes in waiting": those 
we want eventually to promote to official net.jini classes.  When we generate 
the doc for the release we exclude the internal hacks and include the classes in 
waiting  Some people want all the doc, and they can just run javadoc on the 
tree.  Others want to regenrate the doc we sent them (and that command line is 
very complex).  So we have three categories: always doc ("classes in waiting"), sometimes doc (internal hacks), and never doc (generated stuff).

How do I do this with @hide?  With @doc_category (or whatever) we mark the 
internal hacks as @doc_category SunInternal and tell people how to -exclude 
SunInternal if they're regenerating ours.  Voila.

  xxxxx@xxxxx   2000-12-07

------------------
If we add a tag, a possible name for it is @docset, and it would take
a name as an argument.  This plays off the idea that you organize
classes into sets -- you then include or exclude those sets in the
output.

  xxxxx@xxxxx   2001-05-02

-----------------
All the comments in this RFE basically boil down to two requirements:

1) Ability to exclude classes and members
2) Ability to generate more than one set of docs based on labels
    of what to include and exclude. It's important to not be locked 
    into excluding a class in all sets.
    Example:  Exclude classes for outside developers but include them 
    for internal docs

================

We are currently considering adding a @exclude tag that would exclude a
program entity by default, and a command-line option -noexclude that causes
these tags to be ignored.  We believe that this simple solution addresses
the most important and frequent need for this kind of facility.

  xxxxx@xxxxx   2001-08-09

Lowered from priority 3 to 4
  xxxxx@xxxxx   2001-08-23

To correct some misinformation in the above discussion:

javadoc does not use heuristics to map inner class names from the $ form to
the . form.  Instead it uses the inner class attributes that give the correct
mapping.

javadoc determines which members are synthetic by using the Synthetic attribute
that appears in the class file.  These attributes are generated by the compiler.

In additon to both of the above points, javadoc has the actual program sources.

  xxxxx@xxxxx   2001-12-11

Added a new reason at the end of the Description starting "One of the reasons".
  xxxxx@xxxxx   2003-10-06

I propose a combined solution to the "gradiations of exclusion"
Doug Kramer originally mentioned and the inclusion of _Stub and
_Skel type classes. Five new tags @public, @protected, @private,
@package, and @generated plus one new command line switch -incgen
(or however you want to abreviate "include generated"). The first
four tags would be placed to override the actual object visibility,
so that if you had a method that was required to be public, but
you only wanted to document it in say package level runs of javadoc
then you would include the @package tag and run the tool with the
normal -package option. The fifth tag @generated, I think does a
better job of identifing the objective than @hide, @skip or @ignore.
This tag would be placed by tools such as rmic, sfrmic and sfcg
(tools from the IBM SanFrancisco project) which generate code, and
unless the -incgen option is specified would cause the javadoc
generator to bypass that object entirely. Please contact me if
you have any questions on what I propose. -=Chris

This feature was brought up at a javadoc BOF and
3/4 of the people there wanted this feature.
The concensus was it would be great to have this
feature even if it had a simple implementation.

Hello all.
We generate both API level documentation, and internal documentation for our
packages. They have different audiences. The internal javadocs are generated
with -private option of javadoc.
I was about to suggest that what we really need is to override the visibility
modifier of the class/method/field with a different one to be used by javadoc.
But now I see Cabbey has already made that suggestion. So I'll just add my vote
to that form of the solution. This seems a much more elegant solution.
Bruce

Here at Vitria Technology (one of the largest commercial implementations of
Java), we
have the same need for excluding interfaces, classes, methods, etc. and are
(unfor-
tunately) trying to hack the default doclet to implement a @vtexclude tag that
does
the right thing. (When we @vtexclude an interface, we also want to exclude all
the
mentions of methods etc. in the documentation for classes that implement that
interface, as well as to exclude any mention of the interface in the
documentation for
the implemented class.)
I too vote for some supported method of exclusion, and one that would allow for

gradiations of exclusion would be an even better solution.
I would love to hear from anybody who has created any kind of hack that solves
this problem in any way. We need a solution now instead of later. Many thanks.

I was able to do this using @internal tag and -external 
command line argument with a doclet, but only for things 
internal to a class (inner classes, fields, constructors, 
methods), not for classes themselves.  This is because the 
class tree (constructed in ClassTree.java) is not, as far 
as i can see, easily modified.  The ClassTree object 
provides only read methods.  Just doing the @internal tag 
is virtually identical to the @deprecated tag, but the 
@deprecated tag for classes is not handled on the doclet 
side.

I vote for a simple solution. If the javadoc comment 
contains the @exclude tag then the item which the comment 
is for (class, member, whatever) gets excluded from the 
javadoc and anything else in that comment block is ignored. 
This way I can exclude the item or change my mind and re-
include it with just the addition or removal of this one 
tag. ~Tom

I would like to add my vote for an exclude tag.  We 
routinely ship our API that is java based and need to 
exclude out bits that may be inapproriate for others to 
use.  We don't necessarily want to not javadoc the method 
or class because we still wish to use the docs ourselves 
but, we don't want our customer to be notified of the 
method.

I wrote my own doclet to do some of these things. Right now 
if you use @exclude it will exclude any member. Also, a 
class file is not included in less you use @include in the 
class header comment (that could also be a command line 
option). This behavior could easily be changed to do the 
level of exclusion stuff. If people are interested in this 
I could have it all working sometime tommorrow. Let me know 
if you would like the source or compiled doclet. Is there 
some way to stick it here somewhere. Thanks,

James Margaris

Another vote for a way to exclude classes, methods, 
properties, interfaces, etc.

I wouldb be great if @exclude tag makes the item which the 
comment is for (class, member, whatever) excluded from the 
javadoc with anything else in that comment block getting 
ignored.

I also vote for the Cabbey proposal.
Don't have a way of exclusion is really a Javadoc weakness.
Luc
LucLaf@hotmail.com

Hi, I just wanted to update people on my doclet. It can 
exclude entire files or individual members, and allows for 
gradients of exlusion fairly easily. I can offer a jar file 
and the source, as well as examples. The way it works is 
that you can specify the level of a member, either by 
keyword such as "user" or "developer" or a number, then you 
can exclude everything under a certain level. (You can't 
exclude some middle range though) You can also specify what 
unmarked members should be considered as.

So, for example, I can run the exclude doclet to exclude 
everything marked as "user", and consider unmarked members 
to be "user" level. That way the only documentation 
produced is stuff I specifically marked as for developers. 
A few people have contacted me about it and it seems to get 
the job done for them. 

*Feel free to e-mail me for the the doclet.* Also I 
remember reading some time ago that Sun would host a doclet 
that solved this problem. If anyone knows how I could go 
about getting that done please let me know.

I vote to exclude classes, methods, attributes
and interfaces prefixed by the @exclude tag from
the generated html files.

So what's the hold up?  It looks like this has been a 
proposed solution for over three years.  Will this ever 
truly be implemented?

I didn't see what all the fuss was about until EJBs came along.

Having all 5 classes for my Session beans includeed in
package documentation is pointless.  I want one of the
classes documented only.  The rest are EJB implementation
details that I shouldn't have to explain just to avoid empty
entries in the package index.

I'm happy with explicit or category-driven exclusions, but
I'm not happy without either.  What are we supposed to do to
get this ball moved further than it has moved in the last 6
years?

I would love a quick, simple solution to this. Based on simple 
naming conventions is fine with me. I would like to suppress 
JUnit test classes using a simple naming convention, as 
in "suppress javadoc for all classes named "TEST*". Some 
choose to put JUnit tests in a separate tree. Such trees can 
of course can be easily excluded from javadoc. But I find this 
to be an unequivocally *bad* solution. Removing a test from 
package X to package Y means that it no longer has access 
to the package-private classes and members of package X! 
To compensate, one would need to change the scope of 
items from package-private to public, merely to ensure that 
the test harnesses can access them! 

Given the widespread use of JUnit test classes, I think adding 
this feature would be more beneficial than most.

We currently have no plans to implement an exclude ability,
though
we notice it is the most requested feature with 39 votes now
for it. 
The workaround to excluding public classes is to pass in
only the source filenames for the classes you want to
include (works best with 1.4.2).  It should generate the
HTML you expect.
For example, if you have classes package.A, package.B and
package.C, you can exclude class C by supplying:

  javadoc -d doc package/A.html package/B.html

An alternative is to use yDoc Doclet, described at:
http://java.sun.com/j2se/javadoc/faq/index.html#ydoc

By adding @y.exclude, you can exclude classes, fields, and
methods.

Why concider this along the visability lines Java works with.
What we are really saying is, even though its technicaly public (or whatever), it shouldent be for these people...
how about a style like the following (example)...
@visability public internal, partner
@visability private external
then we run into the problem if you are an external partner, should you see it?
which could be fixed with a command line switch, or...
@visibility default=include scope=package
This should cover any possible scenerio, and be a verry simple interface.
Just a suggestion
musheno@users.sourceforge.net

When writing code that uses JFC/Swing, public methods such as actionPerformed() get documented, and a simple "@exclude" (with optional parameters to document the reason for the exclusion) on a per-method/per-class basis would solve my problem.