[erlang-questions] Speaking of comments

[Edmond Begumisa]

On Tue, 14 Dec 2010 02:32:02 +1100, Masklinn <masklinn@REDACTED> wrote:

> On 2010-12-13, at 16:08 , Iñaki Garay wrote:
>>>> On Wed, Dec 8, 2010 at 8:45 PM, Edmond Begumisa  
>>>> <ebegumisa@REDACTED
>>>>> wrote:
>>>>
>>>>> I've thought -- now and then, in the back of my mind -- about  
>>>>> removing
>>>>> comments from actual source all-together (for all languages) and  
>>>>> instead,
>>>>> putting them in companion files that the editor lines up  
>>>>> side-by-side. More
>>>>> like annotating than just traditional commenting.
>> It was my understanding that this is called literate programming, as
>> envisioned by Knuth, although he includes the comment markup in the
>> same file as the code, and uses a preprocessor to extract either the
>> documentation or the code.
>> Knuth's original program was for C and is called CWEB.
> That's exactly the reverse of literate programming: literate programming  
> puts prose first and code second (so instead of marking up the comments,  
> you mark up the code).
>
> 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…).
>
> The core idea stays the same: the core idea of literate programming is  
> that the modules are first and foremost used to communicate with humans  
> via prose, and the code is the second-class citizen.
>
> As to edmond's idea of having code and comments side-by-side, he might  
> be rather interested in Pycco [0] which produces literate-style  
> documentation.

Pycco this looks nice. Rendering wise, it's very close to what I had in  
mind.

> Though it's a generator (it extracts and formats comments within the  
> source file) it does produce something similar to what was described,  
> and it seems to be erlang-compatible.

Yes, that's the difference. It would be good to have this kind of thing  
available while editing and not have to go through a generation step.

- Edmond -


> [0] http://fitzgen.github.com/pycco/
> ________________________________________________________________
> erlang-questions (at) erlang.org mailing list.
> See http://www.erlang.org/faq.html
> To unsubscribe; mailto:erlang-questions-unsubscribe@REDACTED
>


-- 
Using Opera's revolutionary e-mail client: http://www.opera.com/mail/