United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4058216 : stddoclet: Exclude classes/members (e.g. RMI stubs and skeletons) @docset tag

Details
Type:
Enhancement
Submit Date:
1997-06-11
Status:
Open
Updated Date:
2015-12-07
Project Name:
JDK
Resolved Date:
Component:
tools
OS:
generic,other,solaris_2.5.1,windows_95,windows_nt
Sub-Component:
javadoc(tool)
CPU:
generic,x86,sparc
Priority:
P4
Resolution:
Unresolved
Affected Versions:
6
Targeted Versions:
tbd_major

Related Reports
Duplicate:
Duplicate:

Sub Tasks

Description
This 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.


                                    

Comments
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mustang


                                     
2004-07-08
WORK AROUND

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.

###@###.### 2003-10-08
                                     
2003-10-08
EVALUATION

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?

doug.kramer@Eng 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

-----
From ###@###.###  Tue Apr  7 06:34:58 1998

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

-----
From jbloch@taller  Tue Apr  7 18:08:45 1998
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.
doug.kramer@Eng 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.
doug.kramer@Eng 1998-12-15

We are not doing this for 1.2.2
atul.dambalkar@eng 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.
doug.kramer@Eng 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. 
doug.kramer@Eng 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.

ken.arnold@East 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.

doug.kramer@Eng 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.

doug.kramer@Eng 2001-08-09

Lowered from priority 3 to 4
###@###.### 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.

###@###.### 2001-12-11

Added a new reason at the end of the Description starting "One of the reasons".
###@###.### 2003-10-06
                                     
2001-12-11
PUBLIC COMMENTS

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.

###@###.### 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.

jamie.ho@Eng 2001-05-14

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

###@###.### 2001-08-13
                                     
2001-05-14



Hardware and Software, Engineered to Work Together