[erlang-questions] Style wars: junk comments

[Steve Davis]

Also, in case the point got lost, it does let you know which functions are intended to be used outside the app, rather than just ones that must be exported for internal use within, say, the library itself.

On Sep 17, 2012, at 6:23 PM, Steve Davis <steven.charles.davis@REDACTED> wrote:

> 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
>