[erlang-questions] Erlang documentation -- a modest proposal

[Vlad Dumitrescu]

On Wed, Sep 28, 2016 at 7:52 AM, <ok@REDACTED> wrote:

> > Hi,
> > I see an interest in keeping all source code in abstract code at least as
> > a compilation option.
>
> By the time you have included the original spelling of every token,
> all white space, and every comment in your AST (which is what Joe
> was talking about), you have replicated the *concrete* form of the
> source code, just broken up into little bits.


Yes, and sometimes this is just what one needs. Any tool that
processes/transforms source code
needs an AST for the source _before preprocessing_, so that
it can know about macros and ifdefs. Then cross-referencing will include
all types of tokens and all
instances of those, not just those that survived the preprocessor. This is
useful for example when
renaming a function or macro. Even pretty-printing can use this (for
example to gray out the parts of the
source that are currently removed by the preprocessor).

Newer code is much nicer to parse, as heavy usage of macros and ifdefs is
avoided, but
there is always old code that nobody really wants to touch, but has to be
considered. Also we need to
consider the proposed OTP version macros (EEP 44
https://github.com/erlang/eep/blob/master/eeps/eep-0044.md)
that would make it possible to provide multiple versions of a function in
the same file, each possibly with their own
edoc documentation blob (even if it is arguably better to keep the docs
separate, a lot of projects today
use inline docs with edoc).


> If you record the
> source code (in some compressed form), and you record the start and
> length of every term, you can extract the source code for any term
> effortlessly, no concatenation required.
>
> We already have the option to store an AST in a BEAM file,
> I believe.
>

Yes, the key word being _an_ - some use cases need another AST. Processing
source code
for compiling has different requirements than for searching/transforming it.

best regards,
Vlad
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20160928/f94284cb/attachment.htm>