unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#48768: Introducing ability to append to docstring
@ 2021-06-01  0:07 ludvig-faddeev
  2021-06-01  4:53 ` Richard Stallman
  2021-06-01 15:36 ` Lars Ingebrigtsen
  0 siblings, 2 replies; 6+ messages in thread
From: ludvig-faddeev @ 2021-06-01  0:07 UTC (permalink / raw)
  To: 48768


A useful capability would allow one to append to a defun docstring using a defvar.

User could write a brief description for the docstring, and later append more details
from a defvar.

I like my functions to be succinct without an overly long docstring. This makes
the implementation code readily displayed on the visible window, without having
to scroll through an excessively long documentation string.







^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#48768: Introducing ability to append to docstring
  2021-06-01  0:07 bug#48768: Introducing ability to append to docstring ludvig-faddeev
@ 2021-06-01  4:53 ` Richard Stallman
  2021-06-01 14:08   ` Michael Heerdegen
  2021-06-01 15:36 ` Lars Ingebrigtsen
  1 sibling, 1 reply; 6+ messages in thread
From: Richard Stallman @ 2021-06-01  4:53 UTC (permalink / raw)
  To: ludvig-faddeev; +Cc: 48768

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > A useful capability would allow one to append to a defun docstring using a defvar.

  > User could write a brief description for the docstring, and later append more details
  > from a defvar.

Could you show an example of what this would look like, in use?

I'm trying to guess -- though I don't have confidence in my guess --
and I think this might be a useful feature but would be easier to use
with a different interface.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)







^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#48768: Introducing ability to append to docstring
  2021-06-01  4:53 ` Richard Stallman
@ 2021-06-01 14:08   ` Michael Heerdegen
  2021-06-01 14:44     ` bug#48768: [External] : " Drew Adams
  0 siblings, 1 reply; 6+ messages in thread
From: Michael Heerdegen @ 2021-06-01 14:08 UTC (permalink / raw)
  To: Richard Stallman; +Cc: ludvig-faddeev, 48768

Richard Stallman <rms@gnu.org> writes:

>   > A useful capability would allow one to append to a defun docstring
>   > using a defvar.
>
>   > User could write a brief description for the docstring, and later
>   > append more details
>   > from a defvar.
>
> Could you show an example of what this would look like, in use?
>
> I'm trying to guess -- though I don't have confidence in my guess --
> and I think this might be a useful feature but would be easier to use
> with a different interface.

We already have the `function-documentation' symbol property, no?

I wonder what use cases the OP has in mind for that that interface we
have is not sufficient and why the suggested interface would be more
appropriate.

Michael.





^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#48768: [External] : bug#48768: Introducing ability to append to docstring
  2021-06-01 14:08   ` Michael Heerdegen
@ 2021-06-01 14:44     ` Drew Adams
  0 siblings, 0 replies; 6+ messages in thread
From: Drew Adams @ 2021-06-01 14:44 UTC (permalink / raw)
  To: Michael Heerdegen, Richard Stallman
  Cc: ludvig-faddeev@gmx.com, 48768@debbugs.gnu.org

> >   > A useful capability would allow one to append to a defun docstring
> >   > using a defvar.
> >   > User could write a brief description for the docstring, and later
> >   > append more details
> >   > from a defvar.
> >
> > Could you show an example of what this would look like, in use?
> >
> > I'm trying to guess -- though I don't have confidence in my guess --
> > and I think this might be a useful feature but would be easier to use
> > with a different interface.
> 
> We already have the `function-documentation' symbol property, no?
> 
> I wonder what use cases the OP has in mind for that that interface we
> have is not sufficient and why the suggested interface would be more
> appropriate.

Not to mention that you can add to an existing doc string
using advice (old advice or new nadvice, AFAIK).
___


In the days before nadvice, the doc addition appeared
in-line, as part of the doc you see when you use `C-h f'.
Now (unfortunately) we instead insert a link in the
`C-h f' help display, and only if you click that link
do you see (only) that added doc in *Help*.

IOW, you don't get an integrated view of the doc.  One
could argue that this is a plus, not a minus, as it
separates what is provided by the advice.  I think this
is a loss, but I can see that it could be good for each
behavior (integrated or separate) to be possible.
Unfortunately, we only have the separate-display (link)
behavior, not the integrated-doc behavior.

There's one such link for each bit of advice for the
function, and there's no indication that any given bit
of advice provides more doc.

E.g. In my setup command `dired' has two bits of advice,
and this is (the start of) what `C-h f dired' shows:

,----
| dired is an interactive autoloaded compiled Lisp function in
| 'dired.el'.
| 
| It is bound to C-x d, menu-bar file dired.
| 
| (dired DIRNAME &optional SWITCHES)
| 
| :around advice: 'ad-Advice-dired'
| :around advice: 'ls-lisp--dired'
| 
| "Edit" directory DIRNAME--delete, rename, print, etc. some files in it.
| Optional second argument SWITCHES specifies the `ls' options used.
| (Interactively, use a prefix argument to be able to specify SWITCHES.)
| ...
`----

'ad-Advice-dired' and 'ls-lisp--dired' are help links.

That first bit of advice, named `ad-Advice-dired',
only adds doc to the doc string.  Clicking that link
shows (only) that additional doc.

The second bit of advice adds no doc - it is provided
by vanilla Emacs itself (in ls-lisp.el).  Clicking
that second link shows only this in *Help*:

,----
| ls-lisp--dired is an interactive compiled Lisp function in
| 'ls-lisp.el'.
| 
| (ls-lisp--dired ORIG-FUN DIR-OR-LIST &optional SWITCHES)
`----
___

I thought Emacs has a general policy for its code
not to use advice, but `ls-lisp.el' does use it:

  (advice-add 'dired :around #'ls-lisp--dired)





^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#48768: Introducing ability to append to docstring
  2021-06-01  0:07 bug#48768: Introducing ability to append to docstring ludvig-faddeev
  2021-06-01  4:53 ` Richard Stallman
@ 2021-06-01 15:36 ` Lars Ingebrigtsen
  2021-06-01 16:03   ` ludvig-faddeev
  1 sibling, 1 reply; 6+ messages in thread
From: Lars Ingebrigtsen @ 2021-06-01 15:36 UTC (permalink / raw)
  To: ludvig-faddeev; +Cc: 48768

ludvig-faddeev@gmx.com writes:

> A useful capability would allow one to append to a defun docstring
> using a defvar.
>
> User could write a brief description for the docstring, and later
> append more details
> from a defvar.

I do not think that would be a useful interface -- you can append and
change doc strings all you want by manipulating the
`function-documentation' property.

So I'm closing this bug report.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no





^ permalink raw reply	[flat|nested] 6+ messages in thread

* bug#48768: Introducing ability to append to docstring
  2021-06-01 15:36 ` Lars Ingebrigtsen
@ 2021-06-01 16:03   ` ludvig-faddeev
  0 siblings, 0 replies; 6+ messages in thread
From: ludvig-faddeev @ 2021-06-01 16:03 UTC (permalink / raw)
  To: Lars Ingebrigtsen; +Cc: 48768



> Sent: Wednesday, June 02, 2021 at 3:36 AM
> From: "Lars Ingebrigtsen" <larsi@gnus.org>
> To: ludvig-faddeev@gmx.com
> Cc: 48768@debbugs.gnu.org
> Subject: Re: bug#48768: Introducing ability to append to docstring
>
> ludvig-faddeev@gmx.com writes:
>
> > A useful capability would allow one to append to a defun docstring
> > using a defvar.
> >
> > User could write a brief description for the docstring, and later
> > append more details
> > from a defvar.
>
> I do not think that would be a useful interface -- you can append and
> change doc strings all you want by manipulating the
> `function-documentation' property.
>
> So I'm closing this bug report.

If you can tell me how to append, I can use that, but currently, what people
have said do not work.

So appending to a doc-string is not useful.  Appending to a string is the most
useful thing there is !

> --
> (domestic pets only, the antidote for overdose, milk.)
>    bloggy blog: http://lars.ingebrigtsen.no
>





^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2021-06-01 16:03 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2021-06-01  0:07 bug#48768: Introducing ability to append to docstring ludvig-faddeev
2021-06-01  4:53 ` Richard Stallman
2021-06-01 14:08   ` Michael Heerdegen
2021-06-01 14:44     ` bug#48768: [External] : " Drew Adams
2021-06-01 15:36 ` Lars Ingebrigtsen
2021-06-01 16:03   ` ludvig-faddeev

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).