From: Vebjorn Ljosa
Subject: Hide documentation strings in Emacs
Date: 
Message-ID: <cy3itbwecg0.fsf@ljosa.com>
I like documentation strings; keeping the documentation together with
the code makes it easier to keep the documentation up to date.

However, long documentation strings get in the way, and the useful
ones are often the long ones.  It would be nice if Emacs could hide
the better part of long documentation strings, only displaying the
first line and an ellipsis ("...").  Special commands could then let
the user show or hide the rest of the documentation string as needed.

Does such a thing exist?

-- 
Vebjorn Ljosa
From: Dave Morse
Subject: Re: Hide documentation strings in Emacs
Date: 
Message-ID: <3C040CB1.8090104@bomberlan.net>
Vebjorn Ljosa wrote:

> I like documentation strings; keeping the documentation together with
> the code makes it easier to keep the documentation up to date.
> 
> However, long documentation strings get in the way, and the useful
> ones are often the long ones.  It would be nice if Emacs could hide
> the better part of long documentation strings, only displaying the
> first line and an ellipsis ("...").  Special commands could then let
> the user show or hide the rest of the documentation string as needed.
> 
> Does such a thing exist?


Not that I know of.  But I'm only an egg.


It annoys me that text formatting in the docstring is != text 
formatting in the code.  Since docstrings are (in my experience) read 
in code more often than printed by calls to DOCUMENTATION, really a 
better syntax could be invented than the standard:

(defun foo (x y)
   "Foo adds some stuff but is really
just an excuse for a long docstring
that has pesky word wrapping potential.
Arguments: x, y: numbers
Returns: n: a number; b: a boolean"
   (values (+ x y) (plusp x)))

Would be a lot prettier, IMO, something better, but I don't know what.

Even the dumb comment approach is better looking, esp when font-locked:

;; Foo adds some stuff but is really
;; just an excuse for a long docstring
;; that has pesky word wrapping potential.
;; Arguments: x, y: numbers
;; Returns: n: a number; b: a boolean
(defun foo (x y)
   (values (+ x y) (plusp x)))
From: Ruediger Stobbe
Subject: Re: Hide documentation strings in Emacs
Date: 
Message-ID: <e1c078d6.0111280034.631ce7e8@posting.google.com>
Vebjorn Ljosa <·····@ljosa.com> wrote in message news:<···············@ljosa.com>...
> I like documentation strings; keeping the documentation together with
> the code makes it easier to keep the documentation up to date.
> 
> However, long documentation strings get in the way, and the useful
> ones are often the long ones.  It would be nice if Emacs could hide
> the better part of long documentation strings, only displaying the
> first line and an ellipsis ("...").  Special commands could then let
> the user show or hide the rest of the documentation string as needed.
> 
> Does such a thing exist?

Ok, this is not exactly what you want, but you can enclose the
documentation string into folding marks and use emacs folding-mode.
This will show the ellipsis, but unfortunately not the first line.
And it does not look too good. So

   (defun return-nil ()
     ;;{{{ doc
     "This is a long documentation.
   blah blah blah"
     ;;}}}
     nil)

will be folded to

   (defun return-nil ()
     ;;{{{ doc...
     nil)

It looks better when using documentation comments just at the beginning
of the function.

   ;;{{{ This is a long documentation.
   ;; blah blah blah
   ;;}}}
   (defun return-nil () nil)

will look like the following when folded:

   ;;{{{ This is a long documentation...
   (defun return-nil () nil)

You can find folding-mode on Anders Lindgren's Emacs Page. Point your
browser to:

    http://www.csd.uu.se/~andersl/emacs.shtml

ciao
  -- Ruediger
From: Hannu Koivisto
Subject: Re: Hide documentation strings in Emacs
Date: 
Message-ID: <87k7waqzom.fsf@lynx.ionific.com>
Vebjorn Ljosa <·····@ljosa.com> writes:

| However, long documentation strings get in the way, and the useful
| ones are often the long ones.  It would be nice if Emacs could hide
| the better part of long documentation strings, only displaying the
| first line and an ellipsis ("...").  Special commands could then let
| the user show or hide the rest of the documentation string as needed.
| 
| Does such a thing exist?

I'm not aware of anything that does that specifically.  You _might_
be able to beat hideshow to do it (wild guess) but I suspect you
end up doing more work than it is to write from scratch something
that does what you want.  It is actually very easy, won't be many
lines of Emacs Lisp.  Read about overlays in The Emacs Lisp
Reference Manual.

-- 
Hannu
comp.lang.lisp / 2001 / nov