[erlang-questions] Style wars: junk comments

[Vlad Dumitrescu]

Hi,

On Tue, Sep 18, 2012 at 1:29 AM, Steve Davis
<steven.charles.davis@REDACTED> wrote:
> 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.

No, the point was not lost. There's nothing preventing edoc have
another @tag with this meaning. The edoc+spec information can be kept
at runtime too, inside a beam chunk, so that's not an issue. The full
edoc comments are maybe too verbose, but by convention the first
sentence should be exactly the succint description that you mentioned.
Also, when presenting the doc/spec to the user at runtime, the spec
could get simplified, if requested.

What I mean is that I think that your suggestions can be implemented
with tools that already exist and are in use, with the advantage that
many modules already have this information in them. I am not very keen
on having yet another annotation that in time will get out of sync
with the code proper...

regards,
Vlad

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