[erlang-questions] dialyzer output help

[Hugo Mills]

On Mon, Aug 10, 2015 at 02:47:27PM +0200, Loïc Hoguin wrote:
> On 08/10/2015 02:33 PM, Garrett Smith wrote:
> >I use edoc [1] to generate user docs for modules
> 
> I will argue that documentation generated from code isn't
> documentation. After all, if everything is in the code, why not open
> the source file directly, use powerful tools like 'git grep' for
> searching, and read the source? You're guaranteed that the source is
> up to date, even if the little comment above it isn't, and can avoid
> mistakes due to outdated comments.
> 
> If you're going to write documentation, at least don't do it in a
> half assed way. Make it an integral part of your project, not lousy
> comments. Separate the documentation from the code. And respect the
> following rule: *The documentation is always right*. If the code
> doesn't follow the documentation, it's a bug, not the other way
> around.
> 
> Finally, for any large enough project you need three kinds of
> documentation: a function reference (if it's a library), a user
> guide and tutorials. The main reason you need all three is because
> different people learn things in different ways.

   I would also ask for a mid-level architecture guide showing how the
different kinds of pieces should fit together. e.g. "This is the
general flow of data through the processing. Part A can be any
function of <this> type: see A1, A2, A3 for example; part B must do
<thing>, prebuilt ones are B1, B2, or write your own; part C is
entirely optional and can be omitted."

   I've found it's a particular failing of projects with
(autogenerated) function/API references: you get delivered a pile of
parts with detailed specifications, and absolutely no idea of how to
assemble them into something useful. If you're lucky, you'll get
either a trivial example with no idea of how to generalise it, or
you'll get an example of the general case, with no idea of which
pieces you can leave out.

   The flow diagrams in cowboy showing all of the available hooks and
flows are absolutely brilliant from this point of view.

   Hugo.

> (And yep, I still have to work on tutorials for my projects. This is
> actually a recurring question from users who are actively seeking
> them and have to rely on often outdated tutorials.)
> 

-- 
Hugo Mills             | Most administrators wouldn't give their users the
hugo@REDACTED carfax.org.uk | time of day. That's what NTP is for.
http://carfax.org.uk/  |
PGP: E2AB1DE4          |                                            Tim Mullen
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20150810/6a97a7f8/attachment.bin>