diff options
| -rw-r--r-- | doc/src/guide/edoc.asciidoc | 46 | ||||
| -rw-r--r-- | plugins/edoc.mk | 6 | ||||
| -rw-r--r-- | test/plugin_edoc.mk | 112 |
3 files changed, 160 insertions, 4 deletions
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 +---- diff --git a/plugins/edoc.mk b/plugins/edoc.mk index 6f0a82d..7b4331b 100644 --- a/plugins/edoc.mk +++ b/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: diff --git a/test/plugin_edoc.mk b/test/plugin_edoc.mk new file mode 100644 index 0000000..33f3d0f --- /dev/null +++ b/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 <[email protected]>" \ + "@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 |