[erlang-questions] Speaking of comments
Mon Dec 13 17:20:06 CET 2010
On 13 Dec 2010, at 16:32, Masklinn wrote:
> Knuth's own WEB (and CWEB) is extremely complex (out-of-order with macro expansions and hypertext references) and rather unlike usual program writing, a simpler literate idea can be found in Literate Haskell (lhs) where lines of code are prefixed (with `> `) and everything else is comment, yielding rather interesting executable documents.
> Python also has something similar (though extremely reduced in scope) in its "doctests": code lines are prefixed with 4 spaces and sequentially executed, everything else is non-executable text. Doctests can be used either in docstrings (documentary comments, providing executable examples in the APIDoc) or as free-standing documents (documentation, papers, etc…).
http://github.com/uwiger/erl2latex was inspired by a script John Hughes
used to convert erlang source to PDF via LaTEX.
Some form of documentation, eating my own dog food, can be found in:
It got a bit more complex than I had originally intended, since I wanted it
to do a fair job on legacy code. This introduced all sorts of escaping issues.
It was really interesting to work with this, since I noticed that it changes the
way you look at your code - the code really becomes (part of) the documentation.
I'm not going to claim that the above document illustrates that. I quit working
on the code at some point, as I got distracted by other things. But I remember
the feeling, and I've been missing it since then.
If I may quote Joe, he wrote this after trying it:
"I like it *very much* It's strange, I've tried edoc (didn't like it - the output
is ugly) - I wrote my own literate programming system (never used it much -
the code is weirdly ordered)
Used a full book markup system (for the prag book) - overkill for module
Somehow erl2latex strikes the right balance between effort and result -
small effort nice result. (edoc = big effort, no benefit) (book production
system, big effort, big benefit) …
Actually I like this so much I think I'll be using it a lot …"
I don't know if he actually did, but it was a nice thing to say. :)
Ulf Wiger, CTO, Erlang Solutions, Ltd.
More information about the erlang-questions