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

@@ -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
+----

plugins/edoc.mk

@@ -9,13 +9,15 @@ EDOC_OPTS ?=
 
 # Core targets.
 
-docs:: distclean-edoc edoc
+ifneq ($(wildcard doc/overview.edoc),)
+docs:: edoc
+endif
 
 distclean:: distclean-edoc
 
 # Plugin-specific targets.
 
-edoc: doc-deps
+edoc: distclean-edoc doc-deps
 	$(gen_verbose) $(ERL) -eval 'edoc:application($(PROJECT), ".", [$(EDOC_OPTS)]), halt().'
 
 distclean-edoc:

test/plugin_edoc.mk

@@ -0,0 +1,112 @@
+# EDoc plugin.
+
+EDOC_CASES = build docs no-overview opts
+EDOC_TARGETS = $(addprefix edoc-,$(EDOC_CASES))
+
+.PHONY: edoc $(EDOC_TARGETS)
+
+edoc: $(EDOC_TARGETS)
+
+edoc-build: build clean
+
+	$i "Bootstrap a new OTP application named $(APP)"
+	$t mkdir $(APP)/
+	$t cp ../erlang.mk $(APP)/
+	$t $(MAKE) -C $(APP) -f erlang.mk bootstrap $v
+
+	$i "Run EDoc"
+	$t $(MAKE) -C $(APP) edoc $v
+
+	$i "Check that documentation was generated"
+	$t test -f $(APP)/doc/index.html
+	$t test -f $(APP)/doc/$(APP)_app.html
+	$t test -f $(APP)/doc/$(APP)_sup.html
+
+	$i "Distclean the application"
+	$t $(MAKE) -C $(APP) distclean $v
+
+	$i "Check that the generated documentation was removed"
+	$t test ! -e $(APP)/doc/index.html
+	$t test ! -e $(APP)/doc/$(APP)_app.html
+	$t test ! -e $(APP)/doc/$(APP)_sup.html
+
+	$i "Generate a module with EDoc comments"
+	$t printf "%s\n" \
+		"%% @doc erlang-mk-edoc-module" \
+		"-module($(APP))." \
+		"-export([ok/0])." \
+		"" \
+		"%% @doc erlang-mk-edoc-function" \
+		"ok() -> ok." > $(APP)/src/$(APP).erl
+
+	$i "Run EDoc"
+	$t $(MAKE) -C $(APP) edoc $v
+
+	$i "Check that the new module's documentation was generated"
+	$t test -f $(APP)/doc/$(APP).html
+
+	$i "Check that the EDoc comments are in the generated documentation"
+	$t grep -q erlang-mk-edoc-module $(APP)/doc/$(APP).html
+	$t grep -q erlang-mk-edoc-function $(APP)/doc/$(APP).html
+
+	$i "Generate a module with an invalid EDoc comment"
+	$t printf "%s\n" \
+		"-module($(APP)_fail)." \
+		"-export([fail/0])." \
+		"%% @spec lol" \
+		"fail() -> fail." > $(APP)/src/$(APP)_fail.erl
+
+	$i "Check that EDoc errors out"
+	$t ! $(MAKE) -C $(APP) edoc $v
+
+edoc-docs: build clean
+
+	$i "Bootstrap a new OTP application named $(APP)"
+	$t mkdir $(APP)/
+	$t cp ../erlang.mk $(APP)/
+	$t $(MAKE) -C $(APP) -f erlang.mk bootstrap $v
+
+	$i "Generate a doc/overview.edoc file"
+	$t mkdir $(APP)/doc
+	$t printf "%s\n" \
+		"@author R. J. Hacker <rjh@acme.com>" \
+		"@copyright 2007 R. J. Hacker" \
+		"@version 1.0.0" \
+		"@title Welcome to the 'frob' application!" \
+		"@doc 'frob' is a highly advanced frobnicator with low latency," > $(APP)/doc/overview.edoc
+
+	$i "Check that EDoc runs on 'make docs'"
+	$t $(MAKE) -C $(APP) docs $v
+	$t test -f $(APP)/doc/index.html
+
+	$i "Check that the overview.edoc file was used"
+	$t grep -q frobnicator $(APP)/doc/overview-summary.html
+
+edoc-no-overview: build clean
+
+	$i "Bootstrap a new OTP application named $(APP)"
+	$t mkdir $(APP)/
+	$t cp ../erlang.mk $(APP)/
+	$t $(MAKE) -C $(APP) -f erlang.mk bootstrap $v
+
+	$i "Check that EDoc doesn't run on 'make docs'"
+	$t $(MAKE) -C $(APP) docs $v
+	$t test ! -e $(APP)/doc/index.html
+
+edoc-opts: build clean
+
+	$i "Bootstrap a new OTP application named $(APP)"
+	$t mkdir $(APP)/
+	$t cp ../erlang.mk $(APP)/
+	$t $(MAKE) -C $(APP) -f erlang.mk bootstrap $v
+
+	$i "Add edown doclet for EDoc"
+	$t perl -ni.bak -e 'print;if ($$.==1) {print "DOC_DEPS = edown\nEDOC_OPTS = {doclet, edown_doclet}\n"}' $(APP)/Makefile
+
+	$i "Run EDoc"
+	$t $(MAKE) -C $(APP) edoc $v
+
+	$i "Check that the Markdown documentation was generated"
+	$t test -f $(APP)/doc/README.md
+	$t test -f $(APP)/doc/$(APP)_app.md
+	$t test -f $(APP)/doc/$(APP)_sup.md