Ability to list a method in the Constructors summary
Jonathan Gibbons
jonathan.gibbons at oracle.com
Tue Oct 9 21:45:20 UTC 2018
Nir,
Thanks for setting this up; but being realistic, I don't see this going
anywhere.
The main problem is that it is not well-enough defined. Ask any one person
and they may be able to give a well-defined answer, but they may not all
be the same answer.
For example, builders tend to be separate classes, so I don't know what it
means to put builders in their own section. And even factory methods are
often in separate classes, such as the many static methods on
java.util.Collections
or java.nio.file.Paths.get to create a Path object.
The point about people wanting to know how to create objects is well-taken
> I definitely think this is a worthwhile change. One of the first
> things you need to do when working with a new class is figure out how
> to instantiate it. Since half the time the answer is "some factory
> method" that basically requires scanning the entire method list to
> decide if you're using the best approach which is unnecessarily time
> consuming.
But, I believe the best way to address that is a well-written
introduction in the
package-level or class-level documentation for the API in question.
-- Jon
On 10/09/2018 02:13 PM, Nir Lisker wrote:
> 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
> <mailto: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 <mailto: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
>> <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/20181009/b426a30c/attachment-0001.html>
More information about the javadoc-dev
mailing list