Improve documentation

[mateusfccp]

I love this package and use it wherever I can, as I love functional programming. The only thing that bothers me a little is the lack of documentation.

Would'nt it be a nice idea to document the code? I know it's a annoying task, but the results are gratificating, so I'm willing to help. I have a little knowledge on category theory that may help, although it's not a deep knowledge. However, I feel like helping on the documentation will also help me improve my knowledge and skills on FP/CT.

You may set me as collaborator, or we may work simply with gradual PRs, or you may ever decline my proposal.

Thanks, in advance.

---

Documentation status

In-code documentation

• streaming
  • conveyor.dart
  • io.dart
  • pipe.dart
  • source.dart
  • tee.dart
  • text.dart
• unsafe
  • each.dart
  • io.dart
• applicative.dart
• applicative_plus.dart
• avl_tree.dart
• builtins.dart
• dual.dart
• either.dart
• endo.dart
• eq.dart
• evaluation.dart
• foldable.dart
• free.dart
• free_composition.dart
• function.dart (in progress)
• functor.dart
• future.dart
• id.dart
• ihashmap.dart
• ilist.dart
• imap.dart
• io.dart
• iset.dart
• ivector.dart
• lens.dart
• list.dart
• monad.dart
• monad_catch.dart
• monad_plus.dart
• monoid.dart (in progress)
• option.dart
• order.dart
• plus.dart
• plus_empty.dart
• semigroup.dart (in progress)
• state.dart
• task.dart
• trampoline.dart
• traversable.dart
• traversable_monad.dart
• traversable_monad_plus.dart
• tuple.dart
• unit.dart (in progress)

[spebbe]

Hi @mateusfccp!

I completely agree. You are not the first one to suggest this and I believe that at least some basic level of documentation would make the library much more approachable.

I'm not even going to try to come up with any excuses for the current sorry state of the documentation :-) Let's just say I would welcome any help with open arms! If you or others are willing to contribute, how would you feel about starting with a PR based approach and switching to collaborator mode once we've gotten our feet wet?

[mateusfccp]

Hi, @spebbe

I'm fine with your suggestion. I don't have a lot of time, but I'm willing to gradually help with documentation whenever I can. If other people would join me, any help is appreciated.

May we use this issue to track the work?

[spebbe]

Sure! Also, no pressure – any improvement whenever you have the time is appreciated.

[deanriverson]

As another FP fan, I'd like to help a little as well. Would it be convenient to create a docs branch for this work that could be merged into master periodically until we get some momentum? Or should we just submit PRs against master?

[mateusfccp]

@deanriverson, I appreciate your help.

If you feel to, we may initially work on a forked branch of ours. I already started to work on some basic documentation on less complex classes, like Unit, Semigroup and Monoid. I'm going to push it tomorrow so you all can see if you like the approach I'm using by now.

We may then set up some general guidelines for the documentation to be consistent. By now, I'm using the Effective Dart guidelines, as it's a good idea to be in conformance with the community, but we may also define some more specific guidelines if we like to.

[deanriverson]

Agreed, working on a forked repo is the best way to go. I also like the plan of using the Effective Dart guidelines as a baseline and layering more specific guidelines on top if we need to.

Looking forward to seeing your initial work!

[mateusfccp]

Well, here is my initial attempt (unit.dart ):
https://github.com/mateusfccp/dartz/blob/master/lib/src/unit.dart

Some principles I tried to acomplish:

• I tried to be straight and clear;
• I tried to provide a minimal and practical example;
• I tried to left additional not so important details under "Additional details".

For now, I left overriden methods (toString, zero, append) to inherit its documentations from its parents, but they can of course be rewritten if needed.

What do you think about this approach?
@spebbe @deanriverson

[modulovalue]

@mateusfccp I see that you mentioned me (but meant to mention dean). I still would like to give my retrospective opinion about the lack of documentation since I did spend quite some time learning FP mainly by digging through dartz.

IMHO dartz is not lacking documentation. Each element in itself is not complicated to grasp. The hardest part is getting a feel for the full picture. Documenting monoids and monads feels to me like teaching a programmer, while he is programming, what classes are.

The biggest problem that new developers have with fp is that they think that it can't be used to solve real world problems. The example folder in dartz is invaluable. It teaches techniques that are eye opening to someone who is used to OOP and that is what I believe dartz needs more of.

I don't mean to offend you or your efforts, but everytime I tried to convince someone to take a look at fp it never failed because of the lack of documentation but because they didn't see why they would need it. Explaining what a lens (or any other concept for that matter is) is not enough to give them an intuitive understanding for them. They need to see FP in action.

[mateusfccp]

@modulovalue Although I agree partly with you, I don't think this is the point of the documentation. As a functional programmer myself, I found the lack of documentation a little frustrating when started with dartz. For example, I only realized the fact that | could be used for getOrElse after looking at the source code.

There's also the case where a person is still learning FP and know some concepts but not all of them. In this cases, a documentation helps him to learn a little about the concept and its practical utilization, and if they like to, they may learn more about the subject by itself.

[deanriverson]

I definitely agree with @modulovalue that explaining how each of the types can be used is important. But I think even the documentation that @mateusfccp did for a type as simple as Unit shows how important source code documentation can be. It's not that Unit is a difficult concept to grasp, it's more about getting new users (new to FP as well as new to dartz) comfortable with the library and its philosophy. If you're an old hand at FP (I'm sure they exist somewhere) then you know right away that this is the Unit you're used to, but with maybe a few differences. For a newbie, it makes the library infinitely more approachable.

[deanriverson]

@mateusfccp That is a great start! Exactly what I was picturing.

[mateusfccp]

@deanriverson There's details pending as stated by @modulovalue on the commit, but I'm glad you liked it. I'm going to Semigroup now. Feel free to give suggestions.

[spebbe]

Off to a great start! Thank you, people!

@modulovalue, your reasoning rings true to me too. I believe usage examples are the best (and possibly only) way to convey how to "do" FP. On the other hand, I think that some light documentation on the basic purpose and potential quirks of individual types can't hurt either.

I've recently seen a surprising amount of people using parts of dartz, mainly Either, that don't seem to have any desire to go all-in on FP. Either and a couple of other structures are relatively useful in isolation and I think it could be nice to lower the threshold and clear up some confusion about why there is no get, what you should use instead, etc.

Haskell people on the other hand might appreciate some hint that Option is what they would normally call Maybe, etc. ok, a bit of a stupid example, i know, but you get what i mean ;-)

While I like the Unit documentation, I'm not sure who benefits from the category theoretical information in it. People who have studied category theory might just find it obvious and redundant, while people who haven't will probably find it incomprehensible...? I'm very torn about this though... What do you think?

[mateusfccp]

@spebbe I though a little about this. This is why I gave a more tangible explanation with "This means that". Maybe we can switch positions and place the "easier" explanation before and throw the more mathematical explanation on the Additional Details section...

What do you think?

[mateusfccp]

Even so, I don't think it's easy to do this in classes that are by itself the concreteness of mathematical terminology, like Monoid, Semigroup, Functor... How could we make it tangible to people who don't really know algebraic and category terms?