Documentation best practices and tools

[Eric Bailey]

As a follow up to my last post about my simple_cache implementation, I'd like to learn about the current best practices for documenting LFE projects. I read somewhere that Robert doesn't like edoc and though I didn't try, I would imagine it's not fond of processing *.lfe files either. Can it handle the resulting *.beam instead?

Anyway, I've got a few questions.

- What's the preferred method of documenting LFE code these days?
- Are there any LFE-specific tools like edoc or Clojure's Codox or Marginalia?
- How can I programmatically access docstrings of defuns?
- Can defmodule forms include a docstring (like Clojure's ns)?
- Would there be any interest in me writing a tool like Codox to generate HTML and/or Markdown docs?


Cheers,
Eric

[Duncan McGreggor]

On Mon, Aug 17, 2015 at 10:59 AM, Eric Bailey <ifsixw...@gmail.com> wrote:

As a follow up to my last post about my simple_cache implementation, I'd like to learn about the current best practices for documenting LFE projects. I read somewhere that Robert doesn't like edoc and though I didn't try, I would imagine it's not fond of processing *.lfe files either. Can it handle the resulting *.beam instead?

Anyway, I've got a few questions.

- What's the preferred method of documenting LFE code these days?

I can only speak to what I do: standard Lisp-style docstrings, unless there are lots of quotes (e.g., for code samples) in which case I switch to ;; comments. I've been putting those above the functions, but I think I should really put them in the same place as the function docstrings, instead.

 

- Are there any LFE-specific tools like edoc or Clojure's Codox or Marginalia?

Nope.

 

- How can I programmatically access docstrings of defuns?

You can't. The docstrings are thrown out upon compilation. There are some tickets which have been opened related to this:

 * "Add support for (describe ...) in the REPL" - https://github.com/rvirding/lfe/issues/67

 * "Store function docstrings" - https://github.com/rvirding/lfe/issues/87

 * "help/1 in the REPL?" - https://github.com/rvirding/lfe/issues/115

I need to update #87 with a note from #67.

 

- Can defmodule forms include a docstring (like Clojure's ns)?

There's no reason why not: you can add pretty much any metadata you want to defmodule. For instance, you can do this:

(defmodule my-mod

  (version 1.0)

  (docstring "Something helpfully descriptive.")

  (export (noop 0)))

(defun noop ()

  'noop)

And then in the REPL:

> (c "my-mod.lfe")

#(module my-mod)

> (set metadata (my-mod:module_info))

(#(module my-mod)

 #(exports (#(module_info 0) #(module_info 1) #(noop 0)))

 #(attributes

   (#(vsn (198299269673936649315026416761668807783))

    #(version (1.0))

    #(docstring ("Something helpfully descriptive."))))

 #(compile

   (#(options (from_core no_bopt))

    #(version "6.0")

    #(time #(2015 8 17 16 58 23))

    #(source "/Users/oubiwann/lab/lfe/try.lfe.io/my-mod.lfe")))

 #(native false)

 #(md5 #B(149 47 12 214 19 8 241 43 62 150 242 189 203 14 172 103)))

> (car (lists:foldl #'proplists:get_value/2 metadata '(attributes docstring)))

"Something helpfully descriptive."

 

- Would there be any interest in me writing a tool like Codox to generate HTML and/or Markdown docs?

I think so. I might not use it too much at first, but as soon as projects start needing to publish docs, it's going to be useful. In particular, once we support an LFE stdlib, this is going to be something we'll need.

d

 

Cheers,
Eric

--
You received this message because you are subscribed to the Google Groups "Lisp Flavoured Erlang" group.
To unsubscribe from this group and stop receiving emails from it, send an email to lisp-flavoured-e...@googlegroups.com.
To post to this group, send email to lisp-flavo...@googlegroups.com.
Visit this group at http://groups.google.com/group/lisp-flavoured-erlang.
For more options, visit https://groups.google.com/d/optout.

[Robert Virding]

OK, I better describe my thoughts around documentation. :-)

First off I am definitely not one of those say (good) code is self-documenting and doesn't need to be documented. IMAO that is stupid. That said writing good documentation is not always easy and has to be kept up to date, but this is not more of a problem than keeping your function and variable names relevant.

What I don't like is including user documentation in your code files. This I think clutters up the file and makes it harder to find and discern the actual code. You are trying to find a function definition and have to wade past pages of documentation describing how to use a function with lots of examples. This is what I object to. In my code files I want to see documentation which is relevant to me as the coder and that's all.

To be clear this doesn't mean there shouldn't be good documentation for the user, just not mixed up with the code. This what I don't like with edoc and other documentation systems. The edoc output is fine, though I prefer the standard Erlang documentation formats, but it just clutters up the source file. I have the same issue with other systems where the documentation is in the code. It also clutters up the beam files.

I also find that I very seldom use tools like help/1 to read the documentation of a function. I prefer to look in separate documentation. This is course could be due to that I haven't had such systems and so gotten used to not having them. Though this is independent of having documentation in the source files.

Elixir has gone very far along these lines and built-in these documentation/support from the very beginning.

Maybe my view comes from whom I feel I am developing things for, for me it is much more for production systems rather than development systems. I don't know.

But I understand that I am in minority here so something will have to be done. Though there will be a compiler option to strip the documentation out of the beam files. :-)

My question back is: what is actually our goal with the documentation? Is it actually to include the documentation in the source files? Or is this just a way to get them easily accessible to developers through help/1 or equivalent? If it's the latter then I am sure we can work out a system that will make all of us happy.

Robert

[Eric]

On Aug 17, 2015, at 12:35 PM, Robert Virding <rvir...@gmail.com> wrote:

OK, I better describe my thoughts around documentation. :-)

First off I am definitely not one of those say (good) code is self-documenting and doesn't need to be documented. IMAO that is stupid. That said writing good documentation is not always easy and has to be kept up to date, but this is not more of a problem than keeping your function and variable names relevant.

I land somewhere in the middle. In my opinion, short, concise, “self-explanatory” code often doesn’t need any explicit documentation, especially if it’s private. In fact, most private code probably doesn’t need documentation at all. And now I take that back, I think even concise code should have a brief docstring if it’s public/exported.

What I don't like is including user documentation in your code files. This I think clutters up the file and makes it harder to find and discern the actual code. You are trying to find a function definition and have to wade past pages of documentation describing how to use a function with lots of examples. This is what I object to. In my code files I want to see documentation which is relevant to me as the coder and that's all.

I think there’s a happy medium to be found here.

To be clear this doesn't mean there shouldn't be good documentation for the user, just not mixed up with the code. This what I don't like with edoc and other documentation systems. The edoc output is fine, though I prefer the standard Erlang documentation formats, but it just clutters up the source file. I have the same issue with other systems where the documentation is in the code. It also clutters up the beam files.

I agree that the code is no place for an extensive walkthrough, but I don’t mind a short example being thrown into a docstring here and there. I don’t mind it being taken out of beam files. I’m mostly looking for a way to document code such that I can run a tool (perhaps one of my own invention) on it to generate HTML/LaTeX/MD/PDF, etc.

I also find that I very seldom use tools like help/1 to read the documentation of a function. I prefer to look in separate documentation. This is course could be due to that I haven't had such systems and so gotten used to not having them. Though this is independent of having documentation in the source files.

I don’t use it terribly often either, but when I do, it’s a lifesaver. Would there be a way to enable help/1 only when the source *.lfe is present? In that case, I fully support stripping docstrings out of BEAM files.

Elixir has gone very far along these lines and built-in these documentation/support from the very beginning.

Maybe my view comes from whom I feel I am developing things for, for me it is much more for production systems rather than development systems. I don't know.

But I understand that I am in minority here so something will have to be done. Though there will be a compiler option to strip the documentation out of the beam files. :-)

My question back is: what is actually our goal with the documentation? Is it actually to include the documentation in the source files? Or is this just a way to get them easily accessible to developers through help/1 or equivalent? If it's the latter then I am sure we can work out a system that will make all of us happy.

Personally, I want to include the documentation in the source files, but not necessarily the resulting BEAM files (see above). My main goal is to use (and likely develop) a tool with which I can run “magic-tool src/some-mod.lfe” and generate, something like some-mod-docs.html, etc.

An example that illustrates my thinking both in terms of exported HTML and verbosity of docstrings is Codox-generated Compojure docs. The links to source code (on Github, Bitbucket, etc) is particularly desirable.