From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001
From: Erlang/OTP This will all be part of the first paragraph. It can
+stretch over several lines and contain any XHTML markup. ' markup.
+
+ === Headings ===
+
+Section headings, sub-headings, and sub-sub-headings, can be written
+using the following notation:
+```== Heading ==
+ === Sub-heading ===
+ ==== Sub-sub-heading ===='''
+Such a heading must be alone on a line, except for whitespace, and
+cannot be split over several lines. A link target is automatically
+created for the heading, by replacing any whitespace within the text by
+a single underscore character. E.g.,
+```== Concerning Hobbits =='''
+is equivalent to
+``` The abstract layer (defined in {@link erl_syntax}) is nicely
+structured and the node types are context-independent. The layer makes
+it possible to transparently attach source-code comments and user
+annotations to nodes of the tree. Using the abstract layer makes
+applications less sensitive to changes in the {@link //stdlib/erl_parse}
+data structures, only requiring the {@link erl_syntax} module to be
+up-to-date. The pretty printer {@link erl_prettypr} is implemented on top of the
+library module {@link prettypr}: this is a powerful and flexible generic
+pretty printing library, which is also distributed separately. For a short demonstration of parsing and pretty-printing, simply
+compile the included module Also try the {@link erl_tidy} module, as follows:
+
+
+
+== Introduction ==
+
+EDoc lets you write the documentation of an Erlang program as
+comments in the source code itself, using tags on the form
+"`@Name ...'". A source file does not have to contain tags
+for EDoc to generate its documentation, but without tags the result will
+only contain the basic available information that can be extracted from
+the module.
+
+A tag must be the first thing on a comment line, except for leading
+'`%'' characters and whitespace. The comment must be between
+program declarations, and not on the same line as any program text. All
+the following text - including consecutive comment lines - up until the
+end of the comment or the next tagged line, is taken as the
+content of the tag.
+
+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:
+```
+ %% @doc Prints the value X.
+
+ -record(foo, {x, y, z}).
+
+ print(X) -> ...
+'''
+the `@doc' tag is associated with the function `print/1'.
+
+Note that in a comment such as:
+```% % @doc ...'''
+the tag is ignored, because only the first '`%'' character is
+considered "leading". This allows tags to be "commented out".
+
+Some tags, such as `@type', do not need to be associated
+with any program construct. These may be placed at the end of the file,
+in the "footer".
+
+
+== Running EDoc ==
+
+The following are the main functions for running EDoc:
+
+
+
+Note that the function {@link edoc:file/2} belongs to the old, deprecated
+interface (from EDoc version 0.1), and should not be used.
+
+
+== Generic tags ==
+
+The following tags can be used anywhere within a module:
+
+
+
+
+
+== Overview tags ==
+
+The following tags can only be used in an overview file:
+
+
+
+
+== Module tags ==
+
+The following tags can be used before a module declaration:
+
+
+
+
+
+== Function tags ==
+
+The following tags can be used before a function definition:
+
+
+
+
+
+== References ==
+
+In several contexts (`@see' tags, `@link' macros, etc.), EDoc lets
+you refer to the generated documentation for modules, functions,
+datatypes, and applications, using a simple and compact syntax. The
+possible formats for references are:
+
+
+
+
+EDoc will resolve references using the information it finds in
+`edoc-info'-files at the locations specified with the `doc_path'
+option. EDoc will automatically (and somewhat intelligently) try to find
+any local `edoc-info'-files using the current code path, and add them to
+the end of the `doc_path' list. The target doc-directory is also
+searched for an existing info file; this allows documentation to be
+built incrementally. (Use the `new' option to ignore any old info
+file.)
+
+Note that if the name of a module, function or datatype is explicitly
+qualified with an application (as in "`//edoc/edoc_run'"), this
+overrides any other information about that name, and the reference will
+be made relative to the location of the application (if it can be
+found). This makes it possible to refer to e.g. a module "`fred'" as
+"`//foo/fred'" without accidentally getting a reference to
+"`//bar/fred'". You should not use this form of explicit references for
+names that are local to the application you are currently creating -
+they will always be resolved correctly.
+
+Note that module-local references such as `file/2' only work properly
+within a module. In an overview-page like this (i.e., the one you are
+currently reading), no module context is available.
+
+== Notes on XHTML ==
+
+In several places, XHTML markup can be used in the documentation
+text, in particular in `@doc' tags. The main differences from
+HTML are the following:
+
+ Reference syntax Example Scope
+ `Module' {@link edoc_run}, `erl.lang.list' Global
+ `Package.*' `erl.lang.*' Global
+ `Function/Arity' `file/2' Within module
+ `Module:Function/Arity' {@link edoc:application/2} Global
+ `Type()' `filename()' Within module
+ `Module:Type()' {@link edoc:edoc_module()} Global
+ `//Application' {@link //edoc} Global
+ `//Application/Module' {@link //edoc/edoc_doclet} Global
+ `//Application/Module:Function/Arity' {@link //edoc/edoc_run:file/1} Global
+`//Application/Module:Type()' {@link //edoc/edoc:edoc_module()} Global
+
+To write an element like the HTML `
', which has no actual content,
+you can write either the full `
', or better, use the XHTML
+abbreviated form `
'.
+
+Since the purpose of EDoc is to document programs, there is also a
+limited form of "wiki"-syntax available for making program code easier
+to write inline (and to make the doc-comments easier to read).
+See {@section Wiki notation} below for details.
+
+The HTML heading tags `h1' and `h2' are reserved for use by EDoc.
+Headings in documentation source code should start at `h3'. There is
+however a special syntax for writing headings which avoids using
+specific level numbers altogether; see {@section Headings} below for details.
+
+EDoc uses {@link //xmerl. XMerL} to parse and export XML markup.
+
+
+== Wiki notation ==
+
+When EDoc parses XHTML, it does additional pre- and post-processing of
+the text in order to expand certain notation specific to EDoc into
+proper XHTML markup. This "wiki" ([http://en.wikipedia.org/wiki/Wiki])
+notation is intended to make it easier to write source code
+documentation.
+
+ === Empty lines separate paragraphs ===
+
+Leaving an empty line in XHTML text (i.e., a line which except for
+any leading start-of-comment '%' characters contains only
+whitespace), will make EDoc split the text before and
+after the empty line into separate paragraphs. For example:
+```%% @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:
+
+
+Paragraph splitting takes place after the actual XHTML parsing. It only
+affects block-level text, and not e.g., text within `' markup, or
+text that is already within `
Concerning Hobbits
'''
+Thus, headings using this notation should not contain characters that
+may not be part of URL labels, except for whitespace. If you need to
+create such headings, you have to use the explicit XHTML markup.
+
+A hypertext link to a heading written this way can be created using the
+`@section' macro, which transforms the argument text into a label as
+described above. E.g.,
+```@{@section Concerning Hobbits}'''
+is equivalent to writing
+```Concerning Hobbits'''
+
+The above expansions take place before XML parsing.
+
+ === External links ===
+
+Writing a URL within brackets, as in "`[http://www.w3c.org/]'", will
+generate a hyperlink such as [http://www.w3c.org/], using the URL both
+for the destination and the label of the reference, equivalent to writing
+"`http://www.w3c.org/'". This
+short-hand keeps external URL references short and readable. The
+recognized protocols are `http', `ftp', and `file'. This expansion takes
+place before XML parsing.
+
+ === Verbatim quoting ===
+
+In XHTML text, the '`
' character (Unicode `000060',
+known as "grave accent" or "back-quote") can be used for verbatim
+quoting. This expansion takes place before XML parsing.
+
+
+
+
+Examples:
+ ```%% @doc ...where the variable `Foo' refers to... '''
+
+ ```%% @doc ...returns the atom `` 'foo@erlang.org' ''... '''
+
+ `...'
" or
+ "``...''
" will be expanded to
+ "`...
'", where all occurrences of the special XML
+ characters '`<'' and '`&'' (and for completeness, also '`>'') in
+ the quoted text have been escaped to "`<'", "`&'", and
+ "`>'", respectively.
+ All whitespace is stripped from the beginning and end of the
+ quoted text.
+
+ Double back-quotes "``...''
" can be used
+ to quote text containing single '`` ' ''' characters. The automatic
+ stripping of any surrounding whitespace makes it possible to write
+ things like "`` 'foo@bar' ''
".
+
+ To quote text containing "''
" verbatim,
+ explicit `' markup or similar must be used.
```...'''
"
+ will be expanded to "`'", which disables
+ all XML markup within the quoted text, and displays the result in
+ fixed-font with preserved indentation. Whitespace is stripped from
+ the end of the quoted text, but not from the beginning, except for
+ whole leading lines of whitespace. This is
+ useful for multi-line code examples, or displayed
+ one-liners.`
'-character in XML
+ without beginning a new quote, you can write "`'
"
+ (no space between the '`
' and the ''
').
+ You can of course also use the XML character entity
+ "``'".
+ %% @doc ...use the command ```erl -name foo''' to...
+
+
+ %% @doc ...as in the following code:
+ %% ```f(X) ->
+ %% case X of
+ %% ...
+ %% end'''
+
+
+ %% @doc ...or in the following:
+ %% ```
+ %% g(X) ->
+ %% fun () -> ... end
+ %% '''
+
+
+== Macro expansion ==
+
+Before the content of a tag is parsed, the text undergoes macro
+expansion. The syntax for macro calls is:
+
+ @{@name}
+or
+
+ @{@name argument}
+where name and argument are separated by one or more
+whitespace characters. The argument can be any text, which may contain
+other macro calls. The number of non-escaped "@{@
" and
+"`}'" delimiters must be balanced.
+
+ The argument text is first expanded in the current environment, and
+the result is bound to the macro parameter, written
+@{@?}
. (If no argument is given, @{@?}
is
+bound to the empty string.) The macro definition is then substituted
+for the call, and expansion continues over the resulting text. Recursive
+macro expansions are not allowed.
+
+ === User-defined macros ===
+
+Users can define their own macros by using the `def' EDoc
+option; see {@link edoc:file/2} and {@link edoc:get_doc/2} for more
+information.
+
+ === Predefined macros ===
+
+
+
+
+ === Escape sequences ===
+
+To prevent certain characters from being interpreted as delimiters,
+for example to produce the text "@{@date}
@{@docRoot}
@{@docRoot}
will always resolve to the empty
+ string.@{@link reference.
+ description}
@{@link edoc:file/2}
creates the
+ link {@link edoc:file/2}, and `@{@link edoc:file/2. this link}'
+ creates {@link edoc:file/2. this link}.@{@module}
@{@package}
@{@section
+ heading}
@{@type
+ type-expression}
...
'
+ markup and with hypertext links for data types. For example,
+ @{@type {options, List::edoc:option_list()@@}}
+ generates "{@type {options, List::edoc:option_list()@}}". (Cf.
+ {@section Escape sequences} below.)@{@time}
@{@
" in the output, or use a
+'`}'' character in the argument text of a macro call, the
+following escape sequences may be used:
+
+
+
+== Type specifications ==
+
+ === Function specifications ===
+
+The following grammar describes the form of the specifications
+following a `@spec' tag:
+
+@@{
@@}
@@@@
+
+
+
+Examples:
+```
+ %% @spec my_function(X::integer()) -> integer()'''
+```
+ %% @spec (X::integer()) -> integer()'''
+```
+ %% @spec sqrt(float()) -> float()'''
+```
+ %% @spec pair(S, T) -> {S, T}'''
+```
+ %% @spec append(List, List) -> List
+ %% List = [term()]'''
+```
+ %% @spec append(A::List, B::List) -> List
+ %% List = [term()]'''
+```
+ %% @spec open(File::filename()) -> file_descriptor()
+ %% filename() = string() + atom()'''
+```
+ %% @spec close(graphics:window()) -> ok'''
+
+In the above examples, `X', `A', `B',
+and `File' are parameter names, used for referring to the
+parameters from the documentation text. The type variables
+`S', `T' and `List' are used to
+simplify the type specifications, and may be supplied with
+definitions. It is also possible to give definitions for named types,
+which means that the name is simply an alias. (Use the
+`@type' tag to document abstract data types.) If a named type
+is defined in another module, it can be referred to as
+`Module:TypeName(...)'.
+
+Both the '`|'' and the '`+'' character may be
+used to separate alternatives in union types; there is no semantic
+difference. Note that the notation `[Type]' means "proper
+(nil-terminated) list whose elements all belong to `Type'";
+For example, `[atom()|integer()]' means the same thing as
+`[atom()+integer()]', i.e., a proper list of atoms and/or
+integers.
+
+If only a type variable is given for a parameter, as in
+"`pair(S, T) -> ...'", the same variable name may implicitly
+be used as the parameter name; there is no need to write
+"`pair(S::S, T::T) -> ...'".
+
+EDoc automatically extracts possible parameter names from the source
+code, to be used if no parameter name is given in the specification (or
+if the specification is missing altogether). If this fails, EDoc will
+generate a dummy parameter name, such as `X1'. This way, EDoc
+can often produce helpful documentation even for code that does not
+contain any annotations at all.
+
+ === Type definitions ===
+
+The following grammar (see above for auxiliary definitions) describes
+the form of the definitions that may follow a `@type' tag:
+
+
+
+
+ Spec
::=
+
+ FunType Def*
+
| FunctionName FunType Def*
+
+
+ FunctionName
::=
+
+ Atom
+
+
+ FunType
::=
+
+ "(" UnionTypes? ")" "->" UnionType
+
+
+ UnionTypes
::=
+
+ UnionType
+
| UnionType "," UnionTypes
+
+
+ UnionType
::=
+
+ UnionList
+
| Name "::" UnionList
+
+
+ Name
::=
+
+ Variable
+
+
+ UnionList
::=
+
+ Type
+
| Type "+" UnionList
+
| Type "|" UnionList
+
+
+ Type
::=
+
+ TypeVariable
+
| Atom
+
| Integer
+
| Float
+
| FunType
+
| "{" UnionTypes? "}"
+
| "[" "]"
+
| "[" UnionType "]"
+
| TypeName "(" UnionTypes? ")"
+
| ModuleName ":" TypeName "(" UnionTypes? ")"
+
| "//" AppName "/" ModuleName ":" TypeName "(" UnionTypes? ")"
+
+
+ TypeVariable
::=
+
+ Variable
+
+
+ TypeName
::=
+
+ Atom
+
+
+ ModuleName
::=
+
+ Atom
+
| ModuleName "." Atom
+
+
+ AppName
::=
+
+ Atom
+
+
+ Def
::=
+
+ TypeVariable "=" UnionType
+
| TypeName "(" TypeVariables? ")" "=" UnionType
+
+
+ TypeVariables
::=
+
+ TypeVariable
+
| TypeVariable "," TypeVariables
+
+
+(For a truly abstract data type, no equivalence is specified.) The main
+definition may be followed by additional local definitions. Examples:
+```
+ %% @type myList(X). A special kind of lists ...'''
+```
+ %% @type filename() = string(). Atoms not allowed!'''
+```
+ %% @type thing(A) = {thong, A}
+ %% A = term().
+ %% A kind of wrapper type thingy.'''
+
+
+ === Pre-defined data types ===
+
+The following data types are predefined by EDoc, and may not be
+redefined:
+```
+ any()
+ atom()
+ binary()
+ bool()
+ char()
+ cons()
+ deep_string()
+ float()
+ function()
+ integer()
+ list()
+ nil()
+ none()
+ number()
+ pid()
+ port()
+ reference()
+ string()
+ term()
+ tuple()
+'''
+Details:
+
+
+
+ Typedef
::=
+
+ TypeName "(" TypeVariables? ")" Def*
+
| TypeName "(" TypeVariables? ")" "=" UnionType Def*
+
+
+
+== Acknowledgements ==
+
+Since the first version of EDoc, several people have come up with
+suggestions (Luke Gorrie, Joe Armstrong, Erik Stenman, Sean Hinde, Ulf
+Wiger, ...), and some have even submitted code to demonstrate their
+ideas (Vlad Dumitrescu, Johan Blom, Vijay Hirani, ...). None of that
+code was actually included in the Great Rewriting that followed the
+initial public release (EDoc version 0.1), but most of the central
+points were addressed in the new system, such as better modularization
+and possibility to plug in different layout engines, and making EDoc
+understand the application directory layout.
+
+It is now getting too hard to keep track of all the people who have made
+further suggestions or submitted bug reports, but your input is always
+appreciated. Thank you.
diff --git a/lib/edoc/test/edoc_SUITE_data/overview.syntax_tools b/lib/edoc/test/edoc_SUITE_data/overview.syntax_tools
new file mode 100644
index 0000000000..a63c8b26b2
--- /dev/null
+++ b/lib/edoc/test/edoc_SUITE_data/overview.syntax_tools
@@ -0,0 +1,76 @@
+
+@author Richard Carlsson demo.erl
, and execute
+demo:run()
from the Erlang shell. It will compile the
+remaining modules and give you further instructions.
+ erl_tidy:dir("any-erlang-source-dir", [test, old_guard_tests]).
+("test
" assures that no files are modified).
News in 1.4: +
News in 1.3: +
News in 1.2: +
News in 1.1: +