Tom Ball wrote:
In the "Effective Java: Programming Language Guide" by Joshua Bloch, He states
that one of the disadvatages to using Static Factory Methods is that they get
lost with the rest of the API. This can be found on page 8.

	"A Second disadvantage of static factory methods is that they are
	not readily distinguishable from other methods." (Joshua Bloch)

The use of static factory methods is very important and Joshua Bloch does state
the advantages. 
1) They have meaningful names unlike constructors
2) You do not have to instantiate an  customer  on each call
3) These methods can return an  customer  of any subtype of their return type.

I ran this RFE by Joshua Bloch and he felt that it may be worth a try to see if
there could be a special tag for static factory methods, such that they are more
readily viewable/noticable to the user of the API. That way the benefits of
using such methods would be encouraged. Maybe have the static factory methods
grouped after the constructors in the javadoc.  In one instance this would be
beneficial since some constructors will be private and thus uninstantiable by
normal conventions. This special tag (say @factory or so) would help users be
more aware of such methods.

As I mentioned... I avoided needing a @factory tag by using a 
heuristic James came up with:  assume that a method is a static factory 
if it is static and returns the type of the class it's defined in.  For 
example, "static Integer Integer.valueOf(String)" fits this pattern and 
is indeed a static factory.

What surprised me was how extensive static factories are used in the 
JDK.  Integer doesn't just have a static factory, for example; it has six:

     decode(String)
     getInteger(String)
     getInteger(String, int default)
     getInteger(String, Integer default)
     valueOf(String)
     valueOf(String, int radix)

Using the JDK build's list of published JDK packages, there were 
eighty-six classes with at least one static factory method using James' 
heuristic.  So far, I haven't found one that appears wrong.  

  xxxxx@xxxxx   2004-12-24 18:45:42 GMT

N/A

Something we should add for Tiger.
Still need to decide if we need @factory and @nofactory tags to override
the default behavior.
  xxxxx@xxxxx   2002-03-21

Change synopsis from:
  Special Tag for static factory methods

  Separate out static factory methods (new tags required?)
  xxxxx@xxxxx   2002-03-25


  xxxxx@xxxxx   wrote:
My "vote" at this point is for JavaDoc to document static methods which either:  

a) have an explicit @factory tag; or b) return an instance 
of their defining class.  If you folks are happy with this as a strawman 
algorithm, I'll add the support for the @factory tag and pass the doclet 
on to you to do with as you wish.

  xxxxx@xxxxx   wrote:
I see your solution involves adding only a summary table for factory
methods and not separating them out from the detailed listing.  That
seems fine.  

The summary table order would make sense with the constructors
first and static factory methods second.  Would static factory
methods be removed from (or duplicated in) the Method Summary table?

   Constructor Summary
   Static Factory Method Summary
   Inner Class Summary
   Field Summary
   Method Summary

However, Tom suggested the static factory summary be just ahead of
the constructor summary, and that those methods be removed from
the non-static factory method summary.

   Inner Class Summary
   Field Summary
   Static Factory Summary
   Constructor Summary
   Method Summary

Tom wrote:
The reason I put the static factory summary first was because I took from 
Josh's book (and my own experience) that when both constructors and 
factories are defined, factory use is usually preferable.  I prefer
documentation which is organized so that the most interesting bits are 
first.  That may be reaching on my part, however.
  xxxxx@xxxxx   2002-06-12

Tom has donated the fixes.
The modified source files are attached in factories_src.jar.  
The compiles classes are attached in standard_doclet.jar.
See "Suggested Fix" for the diffs.
Tom's comments follow (edited slightly).
Copies of these files are at /java/jdk/ws/tools/doclets/stddoclet/tomball

  xxxxx@xxxxx   2002-07-25


I've finally "1.4-ized" my code and merged it into the standard doclet.  
I've attached both the changed source files and a diff file.  Let me know 
if there's more I can do to get this integrated for you.

Attached is the new standard doclet.  Because it uses the same class names as classes in tools.jar, until the changes are merged into a full build you need 
to run it as: 

$ java -classpath standard_doclet.jar:$JDK/lib/tools.jar         com.sun.tools.javadoc.Main <options>

As we discussed, this doclet collects all static methods whose return types 
are the defining class into a separate Static Factory summary section.  
It also supports the @factory tag, so that classes such as java.util.Collections 
can be better documented.  I leave that as an exercise for you JDK 
documentation experts! :-)

The changes are purposely small and non-disruptive; as you can see from the diff, no lines were changed or removed, only added.  The basic algorithm is 
to create a second method writer for factory methods, subclassed from MethodSubWriter.  Each method writer is called to build up a list of methods 
for its summary, but each one then checks whether each method is owned
by it or not; if not, it is removed from the list.  Ownership is determined 
by calling the isFactoryMethod method.

I had to add a hack in isFactoryMethod because there appears to be a bug in the 
1.4 doclet support.  In 1.4, com.sun.tools.javadoc.ClassDocImpl's equals method 
fails when comparing ClassDocs while it worked in 1.3.1.  I couldn't find 
the source to ClassDocImpl and so punted on fixing it for you.  Instead, 
I compare the ClassDoc names instead of the objects themselves.

It used to be separable, but that was broken in the 1.4 standard doclet 
rewrite.  Maybe I didn't look hard enough, but it didn't seem possible to add 
a separate text resource for additional strings any more.  If you'd like 
a separate doclet, let me know what I missed.

  xxxxx@xxxxx   2002-07-17 (pasted by   xxxxx@xxxxx  )

Please add "Method" to the title, as:
  doclet.Factory_Summary=Static Factory Method Summary

  xxxxx@xxxxx   2002-07-26

We have been cleared by the Tiger planning committee to pursue
this feature.
  xxxxx@xxxxx   2002-08-09

We have gotten general agreement to use the following hierarchy,
where this order would be duplicated for both the summary tables
and the detailed member descriptions:
 
      Public [members]
         Nested classes
         Fields
            Static constant fields
            Static non-constant fields (evil!)
            Instance fields (not quite so evil)
         Static factory methods
         Constructors
         Methods
            Static (non-factory) methods (how common are these?)
            Instance methods
      Protected [members]
         (... exactly as for public members ...)

  xxxxx@xxxxx   2002-08-09

Including the inherited members, we get:

       Public [members]
1          Nested classes
2          Inherited nested classes
           Fields
3             Static constant fields
4             Static non-constant fields (evil!)
5             Instance fields (not quite so evil)
6             Inherited fields
7          Static factory methods
8          Constructors
           Methods
9             Static (non-factory) methods (how common are these?)
10            Instance methods
11            Inherited methods
       Protected [members]
12         Nested classes
13         Inherited nested classes
           Fields
14             Static constant fields
15             Static non-constant fields (evil!)
16             Instance fields (not quite so evil)
17             Inherited fields
18         Static factory methods
19         Constructors
           Methods
20             Static (non-factory) methods (how common are these?)
21             Instance methods
22             Inherited methods

NOTE: Inherited static factory methods (both public and protected) are
not of interest, and so are not included.

  xxxxx@xxxxx   2002-11-09