You are here:
(21 Aug 2016,
<noautolink> ---+!! Documentation Support %TOC% This page explores some of the documentation support provided by Elixir, Erlang, et al. ---++ Introduction <blockquote> Document my code? Why do you think they call it "code"? -- [[%CG_DMC%][T-shirt]] by [[%CG%][Computer Gear & More]] </blockquote> Most programmers realize that documentation can be useful, even if they don't always enjoy creating it. So, it isn't surprising that Elixir (with some help from Erlang) provides strong support for creating documentation. ---++ Elixir <blockquote> Elixir treats documentation as a first-class citizen.</br> This means documentation should be easy to write and easy to read. -- [[%DM_WD%][Elixir - Writing Documentation]] </blockquote> Elixir draws a strong distinction between documentation (which covers code's behavior and interfaces) and comments (which are used by developers working on the code). It encourages the inclusion of internal comments, but has no explicit standards or support for them. In contrast, Elixir has explicit standards (and convenient, unobtrusive support!) for documenting modules and public functions. However, because the goal is to document behavior and interfaces, there is no support for documentation of private functions. [[%GH_ExDoc%][ExDoc]] (Elixir's documentation generator) accepts multi-line strings, using a combination of [[%WP_MD%][Markdown]] syntax and conventions to indicate structure and other distinctions. The strings are stored as [[%GS_MA%][module attributes]] (e.g., =@doc=, =@moduledoc=, =@typedoc=), making them available during compilation and execution. Tooling is provided to run embedded tests, make formatted versions of the strings readable online (e.g., in a web browser or an [[%DM_IEX%][IEx]] session), etc. Most of the Elixir ecosystem is documented in this manner; it is unusual to find an Elixir module in [[%HP%][hex.pm]] that lacks formal documentation in [[%HDP%][hexdocs.pm]]. In Elixir 1.3, =mix= provides the capability to generate various diagrams: * =mix apps.tree= shows the project's applications. * =mix deps.tree= shows all application dependencies. * =mix xref ...= shows all module cross-references. The resulting diagrams are normally displayed in text form, but they can also be used to generate [[%WP_DOT%][DOT]] diagrams. For details, see [[%DS%/Resources#Elixir][Resources: Elixir]]. ---++ Erlang [[%EDoc%][EDoc]] (Erlang's program documentation generator) is similar to ExDoc, but it uses [[%WP_HTML%][HTML]] syntax, rather than Markdown. Erlang also supplies tooling for profiling concurrency and visualizing processes. For details, see [[%DS%/Resources#Erlang][Resources: Erlang]]. Machine-generated documentation for Erlang modules is available from assorted sites. The main Erlang site ([[%ERO%][erlang.org]]) provides multiple versions (e.g., [[%EROD%][erlang.org/doc]], [[%EROD%/search][erlang.org/doc/search]], [[%EROD%/man_index.html][erlang.org/doc/man_index]]). An independent site ([[%Erldocs%][erldocs.com]]) provides a searchable index. ---++ Projects I don't know of any project-specific tooling for documentation, but it seems likely that this will emerge, as developers recognize and address pain points in Phoenix, Nerves, etc. In the meanwhile, Phoenix is familiarizing lots of Elixir developers with existing Elixir and Erlang tooling. For details, see [[%DS%/Resources#Phoenix][Resources: Phoenix]]. ---++ Wish List Here is my personal mixture of ponies (bugs) and unicorns (features). Contributions and corrections welcome! ---+++ Archives Language-based fragmentation is a problem: [[%HP%][Hex.pm]] can manage any BEAM-related package, but many Erlang packages are not represented there (yet :-). Also, most imported Erlang packages don't have online documentation at the function or module level. Meanwhile, the official Erlang documentation could use some love: * The [[%WP_URL%][URL]] (e.g., %EROD%) never changes,<br> making it difficult to link to individual reference manuals. * There are no overview / index pages for the Application Groups. * The [[%EROD%/man_index.html][OTP Reference Page Index]] is simply an alphabetic list. ---+++ Observer Observer is a useful tool for visualization of process graphs, but there's plenty room for improvement. For starters, it should be possible to filter out, select, or summarize sets of processes, select which information to display in what manner, etc. If I have zillions of (say) poolboy processes, just tell me about it once! ---+++ Unicorns <blockquote> Computers should document. Humans should explain. -- me </blockquote> Put another way, we should use computers to harvest information and present it in organized, useful formats. Humans are then left with the (much smaller, but more subtle) task of explaining design goals and approaches (e.g., algorithm and data structure choices). I'd like to see more mechanization and modeling in the areas of application design, package management, etc. There are many things that machines could document for us that are a nuisance to find out manually, e.g.: * What is the call graph for a given process? * What is the dependency tree for module =Foo=? * What messages does each process accept and send? * Which functions use =Foo.bar= and =Foo.baz=? Phoenix (supported by a graph database such as Neo4j) could be used to create a front end to Hex. This could provide integrated system documentation for published libraries, as well as unpublished (or even private) development projects. <!-- * Set DS = Projects/Elixir/DS * Set ELO = http://elixir-lang.org * Set ELO_DM = %ELO%/docs/master * Set ELO_GS = %ELO%/getting-started * Set ERO = http://erlang.org * Set EROD = %ERO%/doc * Set DM_IEX = %ELO_DM%/iex/IEx.html * Set DM_MIX = %ELO_DM%/Mix.html * Set DM_WD = %ELO_DM%/elixir/writing-documentation.html * Set CG = http://www.computergear.com * Set CG_DMC = %CG%/computergear-document-code-tshirt.html * Set EDoc = %EROD%/apps/edoc/chapter.html * Set Erldocs = http://erldocs.com * Set GH_ExDoc = %GH%/elixir-lang/ex_doc * Set GS_MA = %ELO_GS%/module-attributes.html * Set HDP = https://hexdocs.pm * Set HP = https://hex.pm * Set WP_DOT = %WP%/DOT_(graph_description_language) * Set WP_HTML = %WP%/HTML * Set WP_MD = %WP%/Markdown * Set WP_URL = %WP%/Uniform_Resource_Locator --> %ZB%
ore topic actions
Topic revision: r63 - 21 Aug 2016,
Copyright © by the contributing authors. All material on this wiki is the property of the contributing authors.
, Plugin API version
Ideas, requests, problems regarding CFCL Wiki?
Send us email