[erlang-questions] Style wars: junk comments

[Steve Davis]

Well, I guess I was just playing...

However, since you ask, what this approach does do that -spec and edoc do not, is make a module self-documenting even when compiled. 

What's often missing with docs is "what is important here" and "what is the intention". So a distillation, for me at least, is more useful than verbose documentation which does tend to get out of date with the source no matter how well-intentioned.

Also, and again a personal observation, I find -spec confusing as it looks like code and I find myself *reading it as code* and not documentation all too often (maybe I'm just dumb). My preference is a source file without it.

My 2c,
/s

On Sep 17, 2012, at 8:53 AM, Vlad Dumitrescu <vladdu55@REDACTED> wrote:

> Hi,
> 
> On Mon, Sep 17, 2012 at 3:43 PM, Steve Davis
> <steven.charles.davis@REDACTED> wrote:
>> Good naming is often the hardest game.
>> 
>> I have also used "public" rather than "api"... but that too has overtones; but maybe it's better
>> 
>> - and you could go further I guess:
>> 
>> -public([
>>        {foo, [term, list], number, "Finds number of terms in list"},
>>        {bar, ....}
>> ]).
> 
> When this kind of description grows in detail, why not use the edocs
> and the -specs? The edocs could be parsed and stored in an attribute
> available at runtime, and the -spec is more complete that the simple
> types above. A lot of Erlang code already has edoc comments and
> -specs. Why invent a new format that says the same thing?
> 
> Just playing ;-)
> 
> regards,
> Vlad