[mcclim-devel] McCLIM 2.0 in 2008

[Robert Goldman]

Troels Henriksen wrote:
> Robert Strandh <strandh at labri.fr> writes:
> 

> 
>>  >      * Insert docstrings for all exported functionality. If I recall
>>  >        correctly, Robert Strandh spoke with one of the original CLIM
>>  >        spec authors and was told not to worry about copyright issues,
>>  >        so we could just copy from there.
>>
>> I am starting to think that docstrings are evil (because they are
>> mostly noise to the person reading the code).  I would like to discuss
>> the possibility of using (SETF DOCUMENTATION) instead. 
> 
> I think they are just as useful as comments to the person reading the
> code. I'm not a fan of (SETF DOCUMENTATION), as it separates the
> documentation from the code, making it easier for the two to get out
> of sync.

I'd suggest that having docstrings in defgenerics is benign, because
they don't push meaningful code off the screen (assuming one doesn't use
:method).  That would tend to confine the objections to documentation
strings to ones that attach to method definitions and function
definitions.  In that case, one could put a (setf documentation) right
after the definition in question, so that they wouldn't float away from
the code, but wouldn't push the lambda list away from the body of the
definition.  I assume that, the way they are placed, below the slot
definitions, documentation strings for defclass are benign.

Would that be a reasonable compromise?