"Hide" default constructor of abstract final classes

[kevmoo]

If there are no parameters, it is almost certainly NOT useful for anyone looking at docs.

[srawlins]

Couple clarifying questions:

1. Why just default? It seems like maybe any zero-parameter non-factory constructor should be "hidden".
2. Why is final a consideration? It seems like for any abstract class, each constructor with zero parameters (which, by abstract, cannot be called directly) should be "hidden."
3. What if a constructor has a doc comment. Obviously an implicitly declared default constructor cannot have doc comments. But an explicitly declared one?

[srawlins]

As some examples:

abstract class C {
  /// I wrote this comment for a reason.
  C();

  /// Comment
  C.named();

  // No comment.
  C.anotherName();
}

[kevmoo]

But a purely abstract class it makes sense to show the ctor because anyone can extend, right?

[srawlins]

Ah yes, the presense of the constructors is important, if you can extend it. 👍

[jamiewest]

abstract interface class

Hide the default ctor for this as well?

[kevmoo]

Another example here: https://api.dart.dev/main/705c745e19b1b354a2faa32913dbe3f22cc12969/dart-typed_data/TypedDataList-class.html

Showing the (default) constructor here is just confusing.

[srawlins]

This should be easy, and I see the motivation. But @kevmoo I'd love to clarify a few examples:

1. Even if the constructor has parameters, we should hide the constructor?
2. Even if the constructor has a doc comment, we should hide the constructor?

I think (1) sounds fair. I'm not sure on (2).

According to the modifier reference (I love this table), none of the following declarations can be constructed or directly extended (such that someone would want to know super parameters):

• abstract final class
• abstract interface class
• sealed class

(Also mixin and base mixin but those can't have constructors (yet?))

So don't document generative constructors of the above 3 categories.

WDYT @kevmoo ?

[kevmoo]

My understanding, @srawlins - is that for abstract final (maybe others) the only "thing" that can hit the constructor are things in that library – so dartdoc isn't that helpful (although doc comments are helpful for other devs in the library)

We should double-check with someone on the language team, though. @leafpetersen @jakemac53 ?

[srawlins]

@kallentu also implemented the feature and has worked on dartdoc 😁

[leafpetersen]

Don't have strong opinions. No one outside of the library can directly call the constructor, but they could end up indirectly calling it (and so could end up stepping through it, debugging it, etc). I guess dart doc is mostly there for seeing what you can call, so maybe a good argument for hiding it?