You're going to be more specific about what concerns you about the current
format. The Elm community likes to work together towards solutions, not get
into debates. To that end, the tooling and conventions create a
multi-layered system of documentation:
As in any language, *code comments* are used to document *individual lines
of code* whose meaning is not obvious.
*Declaration comments* with the {-| prefix are used to document *public
values and types*. (A "value" is a function or a definition.) These work in
concert with the type annotation. Because the comment and annotation are
displayed together in the rendered docs, they are written together in code.
The *module comment* at the top of the *file/module* gives information
about the module: why it exists as a logical grouping of code. This comment
also includes @docs declarations to define the order that public functions
are documented. They are usually separated by headers (it's just markdown)
and each section may also include a comment. Elm encourages library authors
to use these features so that their module docs are sensible when read top
to bottom. There is also a way to preview docs
<http://package.elm-lang.org/help/docs-preview> prior to publication.
The *README* for each *package* includes information about what the package
does, how to start using it, and what to look for in the more detailed
module docs. They may also include instructions for filing bugs or
upgrading from previous versions of the package or language.
Finally *guides and blog posts* will go into depth and examples on how to
accomplish a* useful unit of work*, such as JSON decoding or refactoring a
union type. These may focus on a module from the core library, one or more
third-party libraries working together, or a language feature.
You will notice that READMEs and guides are not source code files, but are
valuable parts of the hierarchical documentation system.
--
You received this message because you are subscribed to the Google Groups "Elm
Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to elm-discuss+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
