Closed gnprice closed 6 months ago
Hey, thank you for the feedback. Indeed entire SuperListView
class is basically a carbon copy of ListView
, as the class itself doesn't do much else than instantiate the sliver list, which is where the interesting part is.
Now the ListView documentation mostly addresses how to use the ListView, it says very little about the underlying implementation. So I thought maybe it's a good idea to preserve the documentation, but to be honest I find much of Flutter code documentation overly verbose and that is the case here as well.
Your points are good.
I've removed the copied documentation replaced it by references. Admittedly there is still room for improvement.
Looks great, thanks!
This library is very interesting! I'm beginning to read the code to understand what it's doing.
May I gently suggest not copy-pasting the documentation from upstream's ListView and related classes? This is seen currently at today's prerelease version: https://pub.dev/documentation/super_sliver_list/0.2.0-dev.2/super_sliver_list/SuperListView-class.html and in main.
This causes two problems:
SuperListView
. In many places it currently saysListView
when it meansSuperListView
, making it clear it's not yet edited for theSuperListView
context. I figure you'll find and fix those before making a release… but even once you have, it's a lot of text, so it seems like it'll be hard for you to be sure you've gone through every line and caught all the more-subtle details that need updating.SuperListView
is different. After all, I already know more or less howListView
works; and for details where I don't, I already have a place where I can look them up.Instead, the strategy I'd recommend is:
Include as much hand-written documentation as you feel like writing. These docs are great!
Near the top of the [SuperListView] doc, say something like:
And repeat the point in a "see also" item at the end.
Then just leave out all the text that would be copy-pasted.
Similarly, for the individual constructors and so on, copy just the one summary line at the top, and point to the corresponding ListView constructor. For example for
SuperListView.builder
:Then add anything there is to say about the differences… which I'm not sure there is in this example.
SuperListView.builder
has a few parameters not found onListView.builder
, but they correspond directly to fields which have their own docs.