erlef / documentation-wg Goto Github PK
View Code? Open in Web Editor NEWEEF Documentation Working Group
EEF Documentation Working Group
Today, EEP has an Anno field for each entry, which is documented as follows:
Anno - annotation (line, column, file) of the module documentation or of the definition itself (see erl_anno)
The issue, however, is that Erlang has distinct locations for documentation and source code. In order to not introduce a breaking change to EEP 48, I propose:
Anno
to be about the source codeedit_url
metadata field that contains the URL for editing the documentationCurrently, EEP 48 supports a signature field, which is a list of binaries. The signature is pre-rendered. This means tools rendering the documentation only has to concern themselves with printing each line individually.
However, this definition of the signature is not enough for IDEs, which would most likely need to know each argument name and their type, as well as the return type, individually. We should discuss if adding this information is within the scope of EEP 48 and how to effectively add it.
For example, one immediate complication of showing args and return types, is that typespecs in Erlang/Elixir may have multiple clauses, which means there is not a value to show per argument, but multiple of them. Both edoc and Elixir support this style, but not Erlang/OTP XML (afaik).
Hi everyone,
We were asked to make a report on the WG recent efforts. Part of it will also be a video to be presented at CodeBEAM. I think we should touch four topics:
Anything else?
This is a thread to track the progress and any pending tasks that may arise during this effort.
The current idea is that Erlang/OTP XML will be converted to an HTML tree data-structure. This is better than storing HTML as text as we don't have to parse it again.
The tree will have the following format:
Ast :: [Node]
Node :: binary() | {Tag, Attributes, Ast} | {Tag, Ast}
Tag :: binary()
Attributes :: [{binary(), binary()}]
Note: We may remove
{Tag, Ast}
as it can be represented as{Tag, [], Ast}
. The question is if the size will increase considerably or not by doing so.
Note: Currently, EEP 48 requires documentation to be stored as binaries. This means that the HTML tree would have to be converted as term_to_binary and then the whole chunk is converted to term_to_binary again. This is most likely OK, converting a binary with term_to_binary is a fast operation with minimum space increase, but worth noting. The mime type should be something "application/erlang-abstract-format+html".
You can track the current progress here.
<p>
h/1
and friends, see c:i/0
for details<section>
in the refman xml to only be allowed inside <description>
h(ttb,tpl)
,
and .
alone on new-line when after a tagged string.application/erlang+html
format and the EEP-48 format.shell_docs:validate/1
function to follow a stricter dtd.shell_docs:render/*
by using the dtd.<funcs>
tags in the source xml<li>
contents with a <p>
(don't think I will do this as it will change the meaning of things)Now that the doc comments become really first class citizens in the BEAM ecosystem. It would be nice if the compiler could warn about missing edocs on exported functions, not unlike -compile(warn_missing_spec).
It is certainly possible to achieve the same result with a separate tool, but since warn_missing_spec
is implemented in the compiler, it makes sense to follow suite if only for consistency.
I realize that this is very Erlang-centric description, but I am not familiar with other ecosystem languages enough to suggest a more generic problem statement.
This thread documents the progress on generating ExDoc documentation for Erlang projects.
erszcz/edoc@0c81cea can be used to generate chunks compatible with erlang/otp@dd3b015 as follows:
git clone https://github.com/ferd/recon
cd recon
cat >> rebar.config <<END
{plugins,
[
{rebar3_edoc_chunks, {git, "https://github.com/erszcz/edoc.git", {branch, "master"}}}
]}.
{provider_hooks,
[
{post, [{compile, {edoc_chunks, compile}}]}
]}.
END
rebar3 compile
ls _build/default/lib/recon/doc/chunks/
application/erlang+html
format..erl
file / non-dynamic webpage).@since
@deprecated
- partially supported, see erszcz/edoc@ed5f585. EDoc @deprecated
might contain markup, but EEP-48 expects a flat binary()
for this metadata field - currently, all markup is dropped in the chunks.edoc_layout_chunk_markdown
layout and refactor the rest for simplicity:
edoc_layout_chunk_markdown
.NEW-OPTIONS:
/ INHERIT-OPTIONS:
doc comments - I'm not sure how to use these yet, though.-I
, i.e. adding custom include paths, but it hasn't yet occurred to be a problem.2020-04-01 update:
tt
, expr
, see
, strong
tag handling - these pop up in Recon and EDoc itselfex_doc
consuming doc chunks could not generate EDoc documentation due to the types exported to chunk and types exported to Dbgi not matching. This is solved by rewriting all @spec
/ @type
tags to -spec
/-type
attributes (currently only for edoc.erl
)ex_doc
for edoc.erl
(after spec/type rewrite) has some documentation entries truncated, e.g. for the deprecated file/2
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.