stddoclet: Separate out static factory methods and add @factory tag

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 object on each call
3) These methods can return an object 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.

###@###.### 2004-12-24 18:45:42 GMT