[erlang-questions] idea: function meta data

[Joe Armstrong]

2010/8/3 Bob Ippolito <bob@REDACTED>:
> On Tuesday, August 3, 2010, Richard O'Keefe <ok@REDACTED> wrote:
>>>
>>> On Nov 16, 2007 4:49 AM, Vat Raghavan <machinshin2002@REDACTED> wrote:
>>>> i REALLY REALLY like the idea of meta doc strings.
>>>> one possibility for a syntax for it is like pythons', which is something like this ->
>>>>
>>>> def func( bar )
>>>> """  This is the docstring for this function
>>>> """
>>>> and then as someone else said, in the string you can do :
>>>>
>>>> help(Module, func). and the shell emits  ->
>>>> "This is the docstring for this function"
>>
>> Lisp-style docstrings do not make sense for a language like
>> ML or CAML or Clean or Haskell or Mercury or Erlang where a
>> function (A) may have multiple clauses -- so there is no
>> obvious unique place to *put* the docstring and (B) normally
>> use pattern matching -- so the arguments often fail to have
>> *names* that the docstring can talk about.
>>
>> We're left with the Quintus Prolog style of documentation
>> comment, or with EDoc.  Since we already *have* tools for
>> EDoc, let's stick with that.
>>>>
>>>>
>>>> then in the shell
>>>> help(Module, func).
>>
>> That should be something like help(Module, Name, Arity)
>> and there's not the least reason why that couldn't be
>> driven off EDoc.
>
> It'd be easier if edoc was in the BEAM which would imply keeping the
> comments or using an alternative syntax. Compiler directives could
> work but string quoting would be a chore.

There are a couple of problems here - firstly the compiler ignores all
things inside comments
so edoc annotations are not noticed by the compiler. Things in
annotations (ie lines starting
'-') are parsed by the compiler and can be added to the compiled code
(usually retreivable
using module_info:... calls.

Your problem could be solved in two ways - either pre-process a module
and turn the
parse tree of the edoc information into a function that could be
compiled togther with
the other functions in the module. Thus after compilation a function
Mod:edoc_info() would
appear by magic (similar to  Mod:module_info() ...)

Alternatively one could do something about quotes and annotations -
for a long time I'd
though it would be nice to have some kind of mechanism to turn off or
change the meaning of
of the characters inside a quoted string - something like:

     python raw strings   r"......"
     perl multiple quoting qq^hello joe^

There is scope for excessive creativity here - so a guess a few years
contemplation is in order here (unless somebody has already pondered
this for a few years and knows the answer)

The next change would to allow annotation anywhere in the source, at
the moment they are only allowed before you start defining functions.
There was no deep thinking about this.

With a change to the quoting conventions and relaxing the restrictions
on the placement of
annotations then the default would be to compile all annotations into
the module_info function.

/joe

> ________________________________________________________________
> erlang-questions (at) erlang.org mailing list.
> See http://www.erlang.org/faq.html
> To unsubscribe; mailto:erlang-questions-unsubscribe@REDACTED
>
>