Ability to list a method in the Constructors summary

[Nir Lisker]

Hi again,

The activity on the post has more or less stopped. You can read what people
wrote (the points of a comment indicates the amount of people who agree
with it give or take). I found it an interesting read.

To summarize, the majority prefer a JavaDoc comment tag and that the
factory and builder methods will have their own sections. An even further
generalization is to allow users to generate their own sections/tabs.
Someone later suggested new tabs in the constructor summary, which I liked,
but the idea didn't get exposure in time.

There are close to 6k views (though I don't know how many reads). I don't
know if the level of participation is indicative of interest or lack
thereof.

- Nir

On Thu, Oct 4, 2018 at 12:05 PM Nir Lisker <nlisker at gmail.com> wrote:

> Iv'e created a Reddit post [1] if you would like to add anything. I can
> monitor it and when activity ceases I can bring it to your attention to
> draw conclusions.
>
> [1]
> https://www.reddit.com/r/java/comments/9la6vj/opinions_request_would_you_like_to_see_factory/
>
> On Wed, Oct 3, 2018 at 9:45 PM Jonathan Gibbons <
> jonathan.gibbons at oracle.com> wrote:
>
>> 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> 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/20181010/7f87387b/attachment.html>