Re: Scheme file docstring format

[Michael Livshin]

"Jorgen 'forcer' Schaefer" <address@hidden> writes:

> Michael Livshin <address@hidden> writes:
> 
> > > this is reasonable.  then, the requirement becomes: docstring snarfing
> > > should preserve export status of the definition (so that presentation
> > > filters can do their job).
> > 
> > er.  what was the point of moving the docstrings into the comments,
> > again?
> 
> Just recalling from discussions on comp.lang.lisp:
> - Difficult to indent correctly
> - Confusing (removes the body of the function far away from
>   defun/define)

I see.  looks like cosmetics, mostly.

perhaps we should train the reader to do the right thing with
docstrings that look like comments, then?  anything that conserves the
"docstrings are part of the code" property is fine by me.

I'd like these two to be exactly equivalent:

--------------------------------------------

(define (frumple oook)
  "frumple the argument, then do a salto in the air and print a message.
   @var{oook} specifies the oook to frumple."
  ...)

--------------------------------------------

;;@ frumple the argument, then do a salto in the air and print a message
;;@ @var{oook} specifies the oook to frumple.
(define (frumple oook)
  ...)

--------------------------------------------

-- 
All ITS machines now have hardware for a new machine instruction --
BFM
Be Fruitful and Multiply.
Please update your programs.