Add support for (describe ...) in the REPL about lfe HOT 9 CLOSED

The first bit is not too difficult, we just need to define a way to store the comment string inside the module. Either as attributes or have a function which returns the doc strings.

This shouldn't be too difficult either once we have defined the formats. Unfortunately we can't call (describe '#foo:bar/1) as the #' results in a fun and not in the actual values. This is done very early.

Edoc is worse as it know about erlang comments and syntax. We would need a new front-end to it, or some plugins if it supports that. Or use something else. I am not really an edoc fan. :-)

from lfe.

On Sun, Apr 27, 2014 at 6:12 PM, Robert Virding [email protected]:

The first bit is not too difficult, we just need to define a way to store
the comment string inside the module. Either as attributes or have a
function which returns the doc strings.

That's good news!

This shouldn't be too difficult either once we have defined the formats.
Unfortunately we can't call (describe '#foo:bar/1) as the #' results in a
fun and not in the actual values. This is done very early.

Hrm, interesting. Didn't know that's how it worked... Would it be possible
to do something like (describe 'module 'function) or (describe
'module:function)?

Edoc is worse as it know about erlang comments and syntax. We would need a
new front-end to it, or some plugins if it supports that. Or use something
else. I am not really an edoc fan. :-)

Good to know! I've used Javadoc and Pydoc in the past... and it was more of
a pain than anything else. I always ended up writing prose in my
docstrings/comments instead, not using any of the markup. I'm cool with not
even exploring this, then :-)

from lfe.

Opened issue #87 to address the first part of this request.

from lfe.

With regard to @rvirding's second point, I guess we could just do this:

> (describe 'mod 'func n)

where n is the arity. We could also provide a sane default for this:

> (describe 'mod 'func)

where perhaps the default arity selected would be the one with the longest docstring ...

from lfe.

As to the docstring storage ... what about this:

• put it in the module's attributes
• make the key the atom docstrings
• make the value a list of key/value tuples where each key would be #(func n) and the value would be the docstring for that function + arity.
• look-ups would then be done like this: (lists:keyfind #(func n) 1 (mod:module_info 'docstrings)) (which, of course, would be wrappted by a REPL describe or help function (I kind of like the idea of re-using the help name with arities 2 and 3)

from lfe.

Sounds good to me!

from lfe.

Lodox might be of some use. I'd be down to make changes if it helps achieve the goals described here. An interesting feature to note is that lodox-parse:docs/1 produces a giant map of parsed metadata, including docstrings and arglists/patterns.

For reference, parsed function (and macro) maps look like this:

'#m(name     func
    arity    2
    patterns ((x y))
    doc      "func/2 does something really cool.")

from lfe.

Relevant project: https://github.com/erszcz/docsh

from lfe.

See my comment on #211. I'm working on it here for the time being.

from lfe.