Open Levi-Lesches opened 2 months ago
The reason this was all in one file was because of how pub.dev has an example section that references the main.dart file. It was also the only file that got shown back then. I'm not sure if that is still the case now. How would splitting it affect how it's shown there?
See this section at dart.dev:
If the examples are complex and use multiple files, consider making a directory for each example. Otherwise, you can place each one right inside example.
...
If you might publish your package, consider creating an example file with one of the following names:
- example/example[.md]
- example[/lib]/main.dart
- example[/lib]/package_name.dart
- example[/lib]/package_name_example.dart
- example[/lib]/example.dart
- example/README[.md]
When you publish a package that contains one or more of the above files, the pub.dev site creates an Example tab to display the first file it finds (searching in the order shown in the list above).
I think the fundamental problem here is that Pub's example tab is meant to be a quick demo of how to use the package, in the form of a small snippet that is still fully self-contained. This package's example is very thorough, and as a result, is over 3,000 lines -- before the Windows PR adds even more examples and complexity. Even if it does show up on pub.dev, I don't think anyone can read over it and comprehend it, just because of how large it is. If you want to link to a complete example, that's a good thing to do, but I'm not sure the example tab on pub.dev is a great place to do it.
I think the ideal solution would be to split into two examples:
example/example.md
: a simple app with a button that shows a simple notification. Maybe another button to schedule a notification as well. A third button at maximumexample/lib/main.dart
: the complete example that can do everything this package has to offer, and can be run on all supported platforms. This example can be split as described above, with example/lib/windows.dart
, etc, to make comprehending and maintaining it easier, and should probably have helpful comments sprinkled throughout. You can also link to it on the package's README.
This isn't a bug report, I just wanted to discuss before opening a PR. I was working on adding Windows support ( #2349 ) and I noticed the example had grown quite large. I was wondering if simplifying it might make it more helpful, but I understand it's probably not the highest on the priority list.
I was thinking:
receivers.dart
: register streams and background listenerswindows.dart
,android.dart
, etc: platform-specific demosschedule.dart
: schedule-based demos (timezones and repeating)basics.dart
: just the basic "title without body" stuff, maybe w/ actions toomain.dart
: small script to tie it all together@MaikuB If that sounds good to you I can get started on that.