JDK-4058216 : stddoclet: Exclude classes/members (e.g. RMI stubs and skeletons) @docset tag
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 6
  • Priority: P4
  • Status: Resolved
  • Resolution: Won't Fix
  • OS:
    generic,other,solaris_2.5.1,windows_95,windows_nt generic,other,solaris_2.5.1,windows_95,windows_nt
  • CPU: generic,x86,sparc
  • Submitted: 1997-06-11
  • Updated: 2024-04-12
  • Resolved: 2018-01-18
Related Reports
Duplicate :  
JDK-4075128 - Exclude/hide members of the Java source
Duplicate :  
JDK-4178490 - Javadoc needs @hide tag
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
08-07-2004
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
08-10-2003
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
11-12-2001
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
14-05-2001