From cc78f53af903f4e8fad8ac24fcede593ab8f6651 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Sat, 9 Jan 2016 13:36:46 +0100
Subject: Test and document EDoc

A change was made to the automatic EDoc generation when running
'make docs'. It is now only done if a doc/overview.edoc file
exists. This behavior can of course be enabled back by adding
it to the Makefile.
---
 doc/src/guide/edoc.asciidoc | 46 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)

(limited to 'doc')

diff --git a/doc/src/guide/edoc.asciidoc b/doc/src/guide/edoc.asciidoc
index 7827692..9fc1a74 100644
--- a/doc/src/guide/edoc.asciidoc
+++ b/doc/src/guide/edoc.asciidoc
@@ -1,6 +1,48 @@
 [[edoc]]
 == EDoc comments
 
-// @todo Write it.
+Erlang.mk provides a thin wrapper on top of EDoc, an application
+that generates documentation based on comments found in modules.
 
-Placeholder chapter.
+=== Writing EDoc comments
+
+The http://www.erlang.org/doc/apps/edoc/chapter.html[EDoc user guide]
+explains everything you need to know about EDoc comments.
+
+=== Configuration
+
+The `EDOC_OPTS` variable allows you to specify additional
+EDoc options. Options are documented in the
+http://www.erlang.org/doc/man/edoc.html#run-2[EDoc manual].
+
+A common use for this variable is to enable Markdown in doc
+comments, using the `edown` application:
+
+[source,make]
+DOC_DEPS = edown
+EDOC_OPTS = {doclet, edown_doclet}
+
+=== Usage
+
+To build all documentation, you would typically use:
+
+[source,bash]
+$ make docs
+
+Do note, however, that EDoc comments will only be generated
+automatically if the 'doc/overview.edoc' file exists. If you
+do not want that file and still want to generate doc comments,
+two solutions are available.
+
+You can generate EDoc documentation directly:
+
+[source,bash]
+$ make edoc
+
+You can enable automatic generation on `make docs` by adding
+the following to your Makefile:
+
+[source,make]
+----
+docs:: edoc
+----
-- 
cgit v1.2.3