Separate "Methods" and "Extension Methods" sections
Opened this issue · 7 comments
Problem
Currently dart doc mixes methods and extension methods in the same "Methods" section (example).
If the Flutter framework introduced 50+ extension methods on the Widget type, it would flood the Widget's methods with extension methods. It becomes difficult to find Widget's "real" methods.
Solution
Similar to how the "Static Methods" have a separate section (example), we should consider adding a separate section for "Extension Methods"
Thanks for the suggestion. Methods and extension methods are currently integrated, intentionally, to avoid the converse problem: If you were looking for a method available on a class (you don't know that it's an extension method, and why should you?), it would become difficult to find the method.
Why should they be separated? Why would a user be looking for Widget's "real" methods?
you don't know that it's an extension method, and why should you?
I don't think we should treat methods and extension methods like they're exactly the same. Unlike methods, extension methods might not be available depending on your imports. Separating the extension methods might help make this clearer.
it would become difficult to find the method.
Is that true? We already separate static methods, but I wouldn't say they're more difficult to find.
Why should they be separated?
In my opinion, the separate sections would organize the content better :)
it would become difficult to find the method.
Is that true? We already separate static methods, but I wouldn't say they're more difficult to find.
Yes, I think so. If I am looking to call a method on an instance of a class, I look in the Methods section. Sometimes I'm thrown because it turns out I'm looking for a property (like Map.isEmpty for example). And It seems a little weird that operators are in their own list; they could be "alphabetically" in the Methods list.
I don't see static methods as related to instance methods at all; it kind of grates on me that we call them "methods" when they don't use an instance of the enclosing class as a receiver.
Unlike methods, extension methods might not be available depending on your imports.
I think it would be a disservice to "set aside" methods that might require an additional import. I can't think of a reason a user would be prefer to not use the method they we seeking, if it would require importing an additional library.
I think it would be a disservice to "set aside" methods
I think this is the core of our disagreement. I personally like that properties and operators are separated, I find this makes the docs more organized. In my mind, these aren't "set aside" -- they're grouped together!
it kind of grates on me that we call them "methods" when they don't use an instance of the enclosing class as a receiver.
What would you call them instead? Personally, I'm ok with that name as it's a widely understood term that is easily understandable by newbies.
Side note: dart doc also separates classes and exceptions.
What would you call them instead?
Static functions.
... it kind of grates on me that we call them "methods" when they don't use an instance of the enclosing class as a receiver.
It's a hold-over from Smalltalk, where classes are objects and class methods are actual methods whose receiver is the class.
... it's a widely understood term ...
I agree. I doubt that any of our users get confused enough by the term that it's actually worth changing it.
you don't know that it's an extension method, and why should you?
... Unlike methods, extension methods might not be available depending on your imports.
I think that's a valid point. It could also be confusing for users if they look at the current page and see a method on the class, try to use the method in their code, and are then told that the method doesn't exist (because it's an un-imported extension method).
Separating extension methods into a separate section is one solution, but as pointed out it might introduce other sources of confusion.
I don't claim to have a perfect solution, but one other possibility that comes to mind is to clearly annotate which methods are extension methods and where each extension method comes from (how to import it).
A more complex solution would be to have some filtering built in to the output so that a user could ask for subsets such as all methods, only non-extension methods, or maybe only non-inherited methods.
Why should they be separated? Why would a user be looking for
Widget's "real" methods?
They are a little bit like "sealed" method, given they are not part of the class definition and cannot be overridden. Implementing that method in a subclass would be like a "new" method (c# keywords in quotes for trying to be clear on what I mean).
Sorry if I'm saying a bunch of non-sense... 😅