[erlang-questions] idea: function meta data

[Mariano Guerra]

On Thu, Aug 5, 2010 at 4:08 AM, Joe Armstrong <erlang@REDACTED> wrote:
> 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

maybe this can add some ideas to the discussion.

in efene[0] there are local[1] and global[2] attributes.

local attributes get the function name and arity prepended at compile
time and are moved to the top of the ast to make it possible to
compile.

the @doc("doc string") is a "well known" local attribute that is used
by the mod.doc function to generate the documentation, example of
documentation generated using this annotation (and @@moddoc for module
documentation) is here:

http://marianoguerra.com.ar/efene/docs/lib/index.html

disclaimer: not too much documentation but works as an example

here is an example in efene and its transformation to erlang:

mariano@REDACTED:~$ cat test.ifn
@public
@doc("a function that does something")
foo = fn ()
    io.format("hi!~n")

mariano@REDACTED:~$ fnc -t erl test.ifn
-module(test).

-export([foo/0]).

-doc({{foo, 0}, "a function that does something"}).

foo() -> io:format("hi!~n").

[0] http://github.com/marianoguerra/efene
[1] http://marianoguerra.com.ar/efene/docs/reference/toplevel/localattrs.html
[2] http://marianoguerra.com.ar/efene/docs/reference/toplevel/globalattrs.html