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 <[email protected]
<mailto:[email protected]>> 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
<[email protected] <mailto:[email protected]>>
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
<[email protected]
<mailto:[email protected]>> 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
