Finish documentation

[crbelaus]

We must finish Frankt documentation before publishing the first version.

• Finish Readme
• Update Elixir modules documentation
  • Document public functions
  • Document errors
  • Document behaviours
  • Provide some examples
  • Provide typespecs
• Manual
  • Concepts: Frankt channels, action handlers, error handlers, Frankt plugs, etc.
  • Recommendations
  • Examples/Guides
    • Using the default Frankt actions (may be covered with the example application that is being built in Add integration test #11)
    • Sending serialized data from a data-attribute
    • Configuring a Frankt channel with Gettext
    • Configuring a Frankt channel with custom plugs
    • Creating a custom error handler in a Frankt channel
    • Sending data in Frankt actions (form data, element name/value and data-attributes)
    • Creating new Frankt actions to extend the default ones
    • Working with CSRF token protection

[crbelaus]

Edit (2018-06-28): the content of this comment has been added as a checklist to the issue description to make it easier to track the status.

I've been thinking about what to include into the docs.

Basic (readme)

We should update the README to reflect the latest changes. It would be also a good idea to mention two key goals of Frankt:

• It uses the EEx templates you already have for your controllers.
• It does not require you to learn new conceptual burden since it provides a thin layer over Phoenix.Channel. Contrast with Drab which presents you with new concepts such as commanders and specific terminology such as poke or peek.

We should also keep a very small example and contribution guidelines.

Docs

All the docs should be updated to include information for existing modules and public functions. We should also include proper typespecs for guidance.

We should also include some general recommendations:

• Don't use Frankt when a normal HTTP request would suffice.
• Try to authenticate sensible actions in the same way as you would do in a controller.
• Try to provide feedback to the user as soon as possible. Leverage the possibility of pushing multiple messages from the same Frankt action.

Manual

Once we have the readme and the basic documentation we should also create some specific pages with concrete examples:

• Using default Frankt actions.
• Configuring a Frankt channel with Gettext
• Configuring a Frankt channel with custom Plugs.
• Creating a custom error handler in a Frankt channel.
• Sending data in Frankt actions (form data, element name/value, data attribute).
• Creating new Frankt actions to extend the default ones.

Some of those examples could be also written as test applications. This way users could have real code to see and, at the same time, we would have a strong test suite.

[crbelaus]

While the documentation is far from finished and still needs lots of work, I think that it has reached the level in which the basic functionality has been covered.

With this in mind, I am removing this issue from the "v1.0.0" milestone to unlock it and publish Frankt in hex.pm as soon as possible.
The documentation can (and should, in fact) keep being improved and extended after the initial release is published.