diff --git a/lib/edoc/doc/guides/chapter.md b/lib/edoc/doc/guides/chapter.md index b2caea097c6a..760a3a2cb47f 100644 --- a/lib/edoc/doc/guides/chapter.md +++ b/lib/edoc/doc/guides/chapter.md @@ -76,20 +76,20 @@ Tags are associated with the nearest following program construct "of significance" (the module name declaration and function definitions). Other constructs are ignored; e.g., in: -```text - %% @doc Prints the value X. +```erlang +%% @doc Prints the value X. - -record(foo, {x, y, z}). +-record(foo, {x, y, z}). - print(X) -> ... +print(X) -> ... ``` the `@doc` tag is associated with the function `print/1`. Note that in a comment such as: -```text - % % @doc ... +```erlang +% % @doc ... ``` the tag is ignored, because only the first '`%`' character is considered @@ -162,15 +162,15 @@ The following tags can be used anywhere within a module: useful in code containing conditional compilation, when preprocessing is turned on._ (Preprocessing is turned off by default.) E.g., in - ```text - -ifdef(DEBUG). - %% @doc ... - foo(...) -> ... - -endif. - %% @clear + ```erlang + -ifdef(DEBUG). + %% @doc ... + foo(...) -> ... + -endif. + %% @clear - %% @doc ... - bar(...) -> ... + %% @doc ... + bar(...) -> ... ``` the `@clear` tag makes sure that EDoc does not see two `@doc` tags before the @@ -188,13 +188,13 @@ The following tags can be used anywhere within a module: - **`@end`** - [](){: #gtag-end } The text following this tag is always ignored. Use this to mark the end of the previous tag, when necessary, as e.g. in: - ```text - %% ---------------------------------- - %% ... - %% @doc ... - %% ... - %% @end - %% ---------------------------------- + ```erlang + %% ---------------------------------- + %% ... + %% @doc ... + %% ... + %% @end + %% ---------------------------------- ``` to avoid including the last "ruler" line in the `@doc` tag. @@ -218,20 +218,20 @@ The following tags can be used anywhere within a module: function, module or overview-page. The content can be any XHTML text describing the issue, e.g.: - ```text - %% @TODO Finish writing the documentation. + ```erlang + %% @TODO Finish writing the documentation. ``` or - ```text - %% @todo Implement RFC 2549. + ```erlang + %% @todo Implement RFC 2549. ``` These tags can also be written as "`TODO:`", e.g.: - ```text - %% TODO: call your mother + ```erlang + %% TODO: call your mother ``` see [Wiki notation](chapter.md#Wiki_notation) for more information. To-Do @@ -304,28 +304,28 @@ The following tags can be used before a module declaration: Examples: - ```text - %% @author Richard Carlsson + ```erlang + %% @author Richard Carlsson ``` - ```text - %% @author Richard Carlsson - %% [http://example.net/richardc/] + ```erlang + %% @author Richard Carlsson + %% [http://example.net/richardc/] ``` - ```text - %% @author + ```erlang + %% @author ``` - ```text - %% @author carlsson.richard@gmail.com [http://example.net/richardc/] + ```erlang + %% @author carlsson.richard@gmail.com [http://example.net/richardc/] ``` - **`@copyright`** - [](){: #mtag-copyright } Specifies the module copyrights. The content can be arbitrary text; for example: - ```text - %% @copyright 2001-2003 Richard Carlsson + ```erlang + %% @copyright 2001-2003 Richard Carlsson ``` - **`@deprecated`** - [](){: #mtag-deprecated } Mark the module as deprecated, @@ -333,16 +333,16 @@ The following tags can be used before a module declaration: XHTML, and should preferably include a `{@link}` reference to a replacement; as in: - ```text - %% @deprecated Please use the module {@link foo} instead. + ```erlang + %% @deprecated Please use the module {@link foo} instead. ``` - **`@doc`** - [](){: #mtag-doc } Describes the module, using well-formed XHTML text. The first sentence is used as a summary (see the [@doc function tag](chapter.md#ftag-doc) for details). For example.: - ```text - %% @doc This is a very useful module. It is ... + ```erlang + %% @doc This is a very useful module. It is ... ``` - **`@hidden`** - [](){: #mtag-hidden } Marks the module so that it will not @@ -359,14 +359,14 @@ The following tags can be used before a module declaration: arbitrary external resource, such as an article, book, or web site. The content must be well-formed XHTML text. Examples: - ```text - %% @reference Pratchett, T., Interesting Times, - %% Victor Gollancz Ltd, 1994. + ```erlang + %% @reference Pratchett, T., Interesting Times, + %% Victor Gollancz Ltd, 1994. ``` - ```text - %% @reference See Google for - %% more information. + ```erlang + %% @reference See Google for + %% more information. ``` - **`@see`** - [](){: #mtag-see } See the @@ -551,14 +551,14 @@ start-of-comment '`%`' characters contains only whitespace), will make EDoc split the text before and after the empty line into separate paragraphs. For example: -```text - %% @doc This will all be part of the first paragraph. - %% It can stretch over several lines and contain any - %% XHTML markup. - %% - %% This is the second paragraph. The above line is - %% regarded as "empty" by EDoc, even though it ends with - %% a space. +```erlang +%% @doc This will all be part of the first paragraph. +%% It can stretch over several lines and contain any +%% XHTML markup. +%% +%% This is the second paragraph. The above line is +%% regarded as "empty" by EDoc, even though it ends with +%% a space. ``` will generate the following text: @@ -670,32 +670,32 @@ place before XML parsing. Examples: -```text - %% @doc ...where the variable `Foo' refers to... +```erlang +%% @doc ...where the variable `Foo' refers to... ``` -```text - %% @doc ...returns the atom `` 'foo@erlang.org' ''... +```erlang +%% @doc ...returns the atom `` 'foo@erlang.org' ''... ``` -````text - %% @doc ...use the command ```erl -name foo''' to... +````erlang +%% @doc ...use the command ```erl -name foo''' to... ```` -````text - %% @doc ...as in the following code: - %% ```f(X) -> - %% case X of - %% ... - %% end''' +````erlang +%% @doc ...as in the following code: +%% ```f(X) -> +%% case X of +%% ... +%% end''' ```` -````text - %% @doc ...or in the following: - %% ``` - %% g(X) -> - %% fun () -> ... end - %% ''' +````erlang +%% @doc ...or in the following: +%% ``` +%% g(X) -> +%% fun () -> ... end +%% ''' ```` [](){: #Macro_expansion } @@ -778,29 +778,29 @@ argument text of a macro call, the following escape sequences may be used: - **`@{`** - Expands to "`{`". Example: - ```text - %% @doc A macro call starts with the sequence "@{@". + ```erlang + %% @doc A macro call starts with the sequence "@{@". ``` - **`@}`** - Expands to "`}`". Example: - ```text - %% @doc ...{@foo ...{Key, Value@}...}... + ```erlang + %% @doc ...{@foo ...{Key, Value@}...}... ``` - **`@@`** - Expands to "`@`". Example: - ```text - %% @doc Contact us at support@@{@hostname} + ```erlang + %% @doc Contact us at support@@{@hostname} ``` Will generate the text "Contact us at support@vaporware.acme.com" if the macro `hostname` is bound to "`vaporware.acme.com`". Also: - ```text - %% @doc You might want to write something like - %% @@foo that will expand to @foo and does not start - %% a new tag even if it appears first in a line. + ```erlang + %% @doc You might want to write something like + %% @@foo that will expand to @foo and does not start + %% a new tag even if it appears first in a line. ``` [](){: #Type_specifications } @@ -880,47 +880,47 @@ _Table: specification syntax grammar_ Examples: -```text - -spec my_function(X :: integer()) -> integer(). - %% @doc Creates ... +```erlang +-spec my_function(X :: integer()) -> integer(). +%% @doc Creates ... ``` -```text - %% @spec my_function(X::integer()) -> integer() +```erlang +%% @spec my_function(X::integer()) -> integer() ``` -```text - %% @spec (X::integer()) -> integer() +```erlang +%% @spec (X::integer()) -> integer() ``` -```text - %% @spec sqrt(float()) -> float() +```erlang +%% @spec sqrt(float()) -> float() ``` -```text - %% @spec pair(S, T) -> {S, T} +```erlang +%% @spec pair(S, T) -> {S, T} ``` -```text - %% @spec append(List, List) -> List - %% List = [term()] +```erlang +%% @spec append(List, List) -> List +%% List = [term()] ``` -```text - %% @spec append(A::List, B::List) -> List - %% List = [Item] - %% Item = term() +```erlang +%% @spec append(A::List, B::List) -> List +%% List = [Item] +%% Item = term() ``` -```text - %% @spec open(File::filename()) -> FileDescriptor - %% where - %% filename() = string() + atom(), - %% FileDescriptor = term() +```erlang +%% @spec open(File::filename()) -> FileDescriptor +%% where +%% filename() = string() + atom(), +%% FileDescriptor = term() ``` -```text - %% @spec close(graphics:window()) -> ok +```erlang +%% @spec close(graphics:window()) -> ok ``` The first example shows the recommended way of specifying functions. @@ -979,27 +979,27 @@ _Table: type definition grammar_ (For a truly abstract data type, no equivalence is specified.) The main definition may be followed by additional local definitions. Examples: -```text - -type my_list(X) :: [X]. %% A special kind of lists ... +```erlang +-type my_list(X) :: [X]. %% A special kind of lists ... ``` -```text - -opaque another_list(X) :: [X]. - %% another_list() is a kind of list... +```erlang +-opaque another_list(X) :: [X]. +%% another_list() is a kind of list... ``` -```text - %% @type myList(X). A special kind of lists ... +```erlang +%% @type myList(X). A special kind of lists ... ``` -```text - %% @type filename() = string(). Atoms not allowed! +```erlang +%% @type filename() = string(). Atoms not allowed! ``` -```text - %% @type thing(A) = {thong, A} - %% A = term(). - %% A kind of wrapper type thingy. +```erlang +%% @type thing(A) = {thong, A} +%% A = term(). +%% A kind of wrapper type thingy. ``` The first two examples show the recommended way of specifying types. @@ -1184,7 +1184,7 @@ EDoc comes with two sets of doclet/layout pairs: In order to generate doc chunks using `edoc:application/2` or `edoc:files/2` we have to specify which doclet and layout we want to use: -```text +```erlang Opts = [{doclet, edoc_doclet_chunks}, {layout, edoc_layout_chunks}]. ``` @@ -1193,7 +1193,7 @@ Then, it's just a matter of deciding whether we want to generate documentation for the whole application (`edoc:application/2`) or only selected source files (`edoc:files/2`): -```text +```erlang App = my_app. edoc:application(App, Opts). %% or diff --git a/lib/edoc/doc/guides/doc_storage.md b/lib/edoc/doc/guides/doc_storage.md index c9d9708cfc80..b328ab6d6825 100644 --- a/lib/edoc/doc/guides/doc_storage.md +++ b/lib/edoc/doc/guides/doc_storage.md @@ -37,7 +37,7 @@ When generating documentation for EEP-48 edoc uses the format mime type <<"application/erlang+html">>. The documentation content is an Erlang term that represents an HTML like structure. -```text +```erlang -type chunk_elements() :: [chunk_element()]. -type chunk_element() :: {chunk_element_type(),chunk_element_attrs(), chunk_elements()} | unicode:unicode_binary().