Documentation Enhancements Conversation

[leecommamichael]

Hello, I love hooks and I love Flutter. I want to make hooks the de-facto way we write widgets in Flutter, so I want to lower the barrier to entry with snazzy documentation.

Here are some problems I want to solve:

1. Example coverage of features in the package. (number of features which have examples)
2. Effort required to understand the examples. For some of us, this may be easy, just read the code! But for newcomers, seeing is believing. We should be able to share our examples easily!

Here's what I have so far

I have written an example for useAnimationController and hosted the example project using Github Pages. Try it out! https://leecommamichael.github.io/flutter_hooks/#/

If we move in this direction, we can add a build-step in the travis.yml to update the documentation. We can embed the app (which is hosted by GitHub Pages) in our generated Dart documentation or the Readme. I know that dartdoc can embed HTML in iframes, which is perfect. I'm unsure if Markdown can do the same for our README. To make give context when viewing docs, I can have the navigator present the example for the hook the user is looking at in the dart doc page.

It'd be ideal to use something like https://dartpad.dartlang.org/embed-flutter.html, but we'd have to implement it ourselves in order to pull the flutter_hooks package in.

What does everyone think? Do you also find this valuable? Is this a good approach, should I continue?

[rrousselGit]

Hi!

I love the idea.
I'm not too sure that uploading the current example folder is a good idea though.

It'd probably be a better idea to make examples in the dartdoc of each individual hooks, extract these code snippets, and upload them to github gists so that we can run them on dartpad

That should be feasible using some of the more advanced features of dartdoc like macro. That's how Flutter doc works atm

What do you think?

[leecommamichael]

I think it's good to have each example separate to make things more interactive. At the moment DartPad only supports imports from the dart and flutter packages; so even if we could pull examples in from gists, we couldn't run it without copying the source of flutter_hooks above the example. Unless there's another way?

[rrousselGit]

It should be feasible to fork the sources of the library

Like take all the sources, and append them to the example gist

[rrousselGit]

More specifically, we can try merging all the sources of flutter_hooks in a single file, and add it implicitly to our example gists

That should be good enough until there's a proper way to add pubspec dependencies

[leecommamichael]

I'll make more progress as I get free time, but here I've processed the src/ directory with a bash script to produce a cleaned-up single-file library and simply pasted that above an example from the example/ directory. I suppose we would want one such gist per example in the example/ project.

Then we can embed the gists to the generated dart docs as specified here:
https://github.com/dart-lang/dart-pad/wiki/Embedding-Guide

Let me know if you have concerns.

[rrousselGit]

That's epic, good job!

It'd be great to add this to the CI and try to run the existing tests on the generated file.
Since all files are merged into one, it's possible that we get name conflict on private members. So running tests on it will ensure that nothing is broken.

Also, if I remember correctly it's possible to have multiple files on dartpad.
We may want to put the hooks sources as an independent file, as it can get quite big.

I think there's also some situations where this file can be hidden. I think naming it test.dart doesn't show it by default.

[rrousselGit]

If you have the script, I can try to get the CI part done 😊

[leecommamichael]

Here's the script to generate a single-file library.

Multiple-file DartPad isn't going well
This DartPad is backed by this gist. I have two files, but they do not appear to share linkage or scope. I attempted to write some suspicious imports, but I can't import the other file.

I'm going to attempt to use the hard-coded file-names their documentation use like solution.dart and test.dart to fix the issue.

[rrousselGit]

The layout codelab has examples of gists with multiple files: https://gist.github.com/legalcodes/6b00f558718e9f23de5c61503aa1bfe4

So it should be feasible.
But it seems like there's no import directive used.

[leecommamichael]

I tried every permutation, Check it out!

All imports need to be in the same file and the only files that may import are main and test.

[rrousselGit]

Nice! That's a lot better!

I'll explore tomorrow if we can plug this to the dartdoc, such that we'd have:

/// Some documentation
///
/// {@macro whatever}
/// ```dart
/// class Example extends HookWidget {
///   @override
///   Widget build(BuildContext context) {
///     final myAnimation = useAnimationController(...)
///     useAnimation(myAnimation);
///     return Text('$myAnimation');
///   }
/// }
/// ```
/// {@endmacro}
AnimationController useAnimationController(...) {...}

[leecommamichael]

Nice! That's a lot better!

I'll explore tomorrow if we can plug this to the dartdoc, such that we'd have:

/// Some documentation
///
/// {@macro whatever}
/// ```dart
/// class Example extends HookWidget {
///   @override
///   Widget build(BuildContext context) {
///     final myAnimation = useAnimationController(...)
///     useAnimation(myAnimation);
///     return Text('$myAnimation');
///   }
/// }
/// ```
/// {@endmacro}
AnimationController useAnimationController(...) {...}

I've given this some thought: Converting Code Blocks to DartPad seems very close to what we want, but I haven't considered how to access the flutter_hooks file in that scenario.

We may need something like @tool. I'm unsure.

What we really need is for DartPad to be more dynamic. We want a hard-coded test.dart in a gist which contains the library, but to be able to pass in a code-block to be used for the user-editable main.dart.

[simc]

I tried to implement something similar for Hive and I ended up forking dartpad and dart-services. Not many changes are necessary to include a package. It works quite well.

[rrousselGit]

Ah, forgot to answer~

@leisim, could you explain a bit more in what you had to do? 😄