Yes, I'm curious what exactly your concerns are with the current documentation system. Seems like removing all documentation from the source code would just make it harder to notice mistakes.
On Sun, Dec 11, 2016 at 9:52 AM, Max Goldstein <[email protected]> wrote: > 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 [email protected]. > For more options, visit https://groups.google.com/d/optout. > -- 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 [email protected]. For more options, visit https://groups.google.com/d/optout.
