Ability to list a method in the Constructors summary

[Jonathan Gibbons]

Nir,

The level of interest could be interesting.  I do note that there is 
more of a trend in
Java API design these days to use factory methods, e.g. the ".of(...)" 
pattern so that
would lend weight to such a feature.

That being said, it would then come down to the level of design and 
implementation
work required to effect such a change, and whether the cost is worth the 
benefit.

There would no doubt be a bikeshed discussion on where such an 
annotation might go,
or whether to just use a documentation tag within the comment.  The best 
precedent
would be @FunctionalInterface, but that is in java.lang, and there is 
quite a high bar
to adding types to that package. Then we would have to look at changing the
organization of the page, to move selected methods up into the 
Constructors table,
and possibly renaming it to "Constructors and Factory Methods" or 
something like that.

A simpler variation would be just another tab in the method table for 
"Factory Methods",
perhaps automatically determining static methods that return the 
enclosing type. It
would be interesting to see how many false-positives that would catch 
(i.e. without even
using an annotation.)

-- Jon

On 10/02/2018 11:49 PM, Nir Lisker wrote:
> Hi Jon,
>
> Thanks for the info.
>
> If I bring it up on the Java subreddit and see what people say, would 
> it count as a measure for interest? How is "sufficient interest" 
> evaluated, more or less?
>
> - Nir
>
> On Wed, Oct 3, 2018 at 2:27 AM Jonathan Gibbons 
> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> wrote:
>
>
>
>     On 10/02/2018 06:54 AM, Nir Lisker wrote:
>>     Hi,
>>
>>     Many static methods are used to obtain an instance of a class,
>>     functioning as a de-facto constructor and sometimes replacing it
>>     altogether. These are factory or builder methods and the like.
>>
>>     The problem is that while they function as constructors, they are
>>     hidden between the rest of the methods in the JavaDoc. It is my
>>     understanding that the Constructors section shows how to create
>>     an instance, while the Methods section shows how to use it. In
>>     this case, the aforementioned methods will fit better in the
>>     Constructors section.
>>
>>     One way this can be solved is via an annotation on the method
>>     that would list it under the Constructors, used at the developers
>>     discretion. As an example, Toolkit is a singleton:
>>
>>         public class Toolkit {
>>
>>             private final Toolkit TOOLKIT;
>>
>>             private Toolkit() {  ...  }
>>
>>             @Constructor
>>             public static getDefaultSystemToolkit() { return TOOLKIT; }
>>         }
>>
>>
>>     The annotation shows the intended way for a developer to obtain
>>     the instance.
>>
>>     I can submit an RFE if this is plausible. Otherwise, I'm open for
>>     other solutions if you agree with the problem I presented.
>>
>>     - Nir
>
>     Nir,
>
>     It's not an unreasonable request, and has been suggested before,
>     dating back to 2002.
>
>     That being said, there has not been sufficient interest to make it
>     happen.
>
>     See this JBS issue for one of the early requests:
>     https://bugs.openjdk.java.net/browse/JDK-4619333
>
>     -- Jon
>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20181003/59c0c26b/attachment.html>