GNU bug report logs - #9115
`documentation' should let you choose whether to include `usage'

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 9115 in the body.
You can then email your comments to 9115 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 24.0.50; `documentation' should not return args list for CL defun*.
Date: Mon, 18 Jul 2011 08:05:22 +0200

Hi,
documentation return the list of arg for the defun*'s:(choose a short one)

--8<---------------cut here---------------start------------->8---
(documentation 'ert--remove*)
"Does not support all the keywords of remove*.

(fn X LIST &key KEY TEST)"
--8<---------------cut here---------------end--------------->8---

It's annoying for function not documented because it return only list of
args instead or returning nil.


In GNU Emacs 24.0.50.1 (i686-pc-linux-gnu, GTK+ Version 2.24.4)
 of 2011-07-16 on thierry-MM061
Windowing system distributor `The X.Org Foundation', version 11.0.11001000
Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: fr_FR.utf8
  value of $XMODIFIERS: nil
  locale-coding-system: utf-8-unix
  default enable-multibyte-characters: t

Major mode: Emacs-Lisp

Minor modes in effect:
  TeX-PDF-mode: t
  minibuffer-depth-indicate-mode: t
  auto-image-file-mode: t
  eldoc-mode: t
  show-paren-mode: t
  display-time-mode: t
  diff-auto-refine-mode: t
  recentf-mode: t
  savehist-mode: t
  shell-dirtrack-mode: t
  anything-dired-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
<right> <right> <right> <right> <right> <right> <right> 
<right> <right> <right> <right> <right> <right> <right> 
<right> <right> <right> <right> <right> <right> <right> 
<right> <right> <right> <right> <right> SPC d o c C-M-x 
<down> <down> <down> <down> <tab> <tab> <down> <down> 
<down> C-z C-g <up> <down> <left> <left> <left> <left> 
; <up> <up> <up> <up> <right> <right> <right> <right> 
<right> <right> <right> <right> <right> <right> <right> 
<right> <right> <right> <right> <right> <right> <right> 
<right> <right> <right> <right> <right> <right> <right> 
<right> <right> <right> <right> <right> <right> <right> 
<right> <right> <backspace> <backspace> C-M-x <down> 
<down> <down> <down> <tab> <tab> <down> <down> <down> 
C-z <down> C-z <up> C-z <down> <down> <down> <down> 
C-z <down> <down> <down> <down> <down> <down> <down> 
<down> C-z <down> <down> C-z <down> <down> C-z <down> 
C-z <down> C-z <down> C-z <down> C-z <down> C-z C-g 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <backspace> <backspace> <backspace> <backspace> 
<backspace> <return> C-x C-s <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <up> <up> <up> <up> <up> <up> <up> <up> <up> 
<up> <up> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <right> <right> <right> 
<right> <right> <right> <right> <right> <right> <right> 
<right> <right> <right> <right> <right> <right> <right> 
<right> <right> <right> <right> M-x r e p o r t <r
eturn>

Recent messages:
anything-c-get-first-line-documentation

Quit
anything-c-get-first-line-documentation

Quit
Auto-saving...done
Saving file /home/thierry/labo/anything-config-qp/anything-config.el...
Wrote /home/thierry/labo/anything-config-qp/anything-config.el


Load-path shadows:
None found.

Features:
(shadow emacsbug flow-fill mailalias smtpmail epa-mail smiley gnus-cite
mail-extr gnus-async gnus-bcklg qp gnus-ml nndraft nnmh nndoc utf-7
nnimap utf7 nnml nnfolder rot13 netrc network-stream starttls tls
gnus-agent gnus-srvr gnus-score score-mode nnvirtual gnus-msg nntp
gnus-cache gnus-dired find-func help-mode view cal-iso preview prv-emacs
tex-buf reftex-vcr reftex-dcr reftex-auc reftex reftex-vars font-latex
latex tex-style tex latexenc imenu rst sh-script vc-rcs vc-git xgit-dvc
xgit xgit-annotate dvc-annotate xgit-log conf-mode xhg-dvc xhg
xhg-annotate xhg-mq xhg-log bzr-core xdarcs-core xgit-core xhg-core
xmtn-minimal tla smerge-mode newcomment dvc-state dvc-config dvc-diff
dvc-fileinfo diff sendmail dvc-cmenu dvc-about dvc-version dvc-revlist
uniquify em-unix em-script em-prompt em-ls em-hist em-pred em-glob
em-dirs em-cmpl em-basic esh-opt em-banner em-alias esh-var esh-io
esh-cmd esh-ext esh-proc esh-groups eshell esh-module esh-mode align-let
server googlecl google-maps google-maps-static google-maps-geocode
google-maps-base json simple-call-tree el-expectations el-mock csv2org
iedit zop-to-char mule-util elscreen smallurl mm-url xml-weather
rectangle-utils tv-utils pcvs pcvs-parse pcvs-info pcvs-defs
auto-document autodoc mb-depth ioccur moz cl-info slime-xref-browser
slime-banner slime-tramp slime-asdf slime-fancy slime-fontifying-fu
slime-package-fu slime-references slime-scratch slime-presentations
slime-fuzzy slime-fancy-inspector slime-c-p-c slime-editing-commands
slime-autodoc slime-parse slime-repl slime hideshow hyperspec
slime-autoloads boxquote rect image-file newsticker newst-treeview
newst-plainview newst-reader newst-ticker newst-backend ledger-config
ledger esh-arg esh-util lpr woman man two-column em-term term ehelp
electric esh-toggle em-xtra flymake pdbtrack eldoc-eval eldoc no-word
regex-tool whitespace paren time dired-tar dired-extension image-dired
yaoddmuse skeleton sgml-mode emms-mplayer-config emms-playlist-limit
emms-volume emms-volume-amixer emms-i18n emms-history emms-score
emms-stream-info emms-metaplaylist-mode emms-bookmarks
emms-lastfm-client parse-time emms-cue emms-mode-line-icon emms-browser
sort emms-playlist-sort emms-last-played emms-player-xine
emms-player-mpd tq emms-playing-time emms-lyrics emms-url hl-line
emms-tag-editor emms-mark emms-mode-line emms-cache emms-info-ogginfo
emms-info-mp3info emms-playlist-mode emms-player-vlc emms-player-mplayer
emms-info emms-streams later-do emms-source-playlist emms-source-file
emms-player-simple emms-setup emms emms-compat winner dvc-init bzr-gnus
tla-gnus xgit-gnus xhg-gnus gnus-art mm-uu mml2015 mm-view mml-smime
smime dig nnir gnus-sum nnoo gnus-group gnus-undo nnmail mail-source
gnus-start gnus-spec gnus-int gnus-range gnus-win gnus gnus-ems nnheader
dvc-gnus tla-core tla-autoconf tla-defs dvc-log vc vc-dispatcher
dvc-unified dvc-tips dired-x ediff-merg ediff-diff ediff-wind ediff-help
ediff-util ediff-mult ediff-init ediff dvc-autoloads dvc-core dvc-lisp
dvc-buffers dvc-ui dvc-register dvc-utils dvc-emacs ewoc dvc-defs
dvc-site psvn log-edit pcvs-util add-log diff-mode htmlize-hack htmlize
muse-colors muse-docbook muse-texinfo texnfo-upd texinfo muse-latex
muse-html muse-xml-common muse-wiki cus-edit cus-start cus-load
muse-publish muse-project muse-protocols muse-regexps muse
muse-nested-tags muse-mode muse-autoloads org-config-thierry org-crypt
cal-china lunar solar cal-dst cal-bahai cal-islam cal-hebrew holidays
hol-loaddefs vc-hg org-wl org-w3m org-vm org-rmail org-mhe org-mew
org-irc org-jsinfo org-infojs org-html org-exp ob-exp org-exp-blocks
org-info org-gnus org-docview org-bibtex org-bbdb org-agenda appt
diary-lib diary-loaddefs org-annotation-helper org-capture org-mks
remember org-remember org-datetree config-w3m mime-w3m w3m doc-view
jka-compr image-mode timezone w3m-hist w3m-fb w3m-ems w3m-ccl ccl
w3m-favicon w3m-image w3m-proc w3m-util mime eword-decode mel path-util
mime-parse std11 luna mime-def alist mcharset mcs-20 mcs-e20 pces
pces-e20 pces-20 broken pcustom poe pym static apel-ver product w3m-load
addressbook-bookmark message rfc822 mml mml-sec mm-decode mm-bodies
mm-encode mail-parse rfc2231 rfc2047 rfc2045 ietf-drums mailabbrev
mail-utils gmm-utils mailheader firefox-protocol bookmark-uzbl-handler
bookmark-firefox-handler bookmark-extensions org ob-emacs-lisp ob-tangle
ob-ref ob-lob ob-table org-footnote org-src ob-comint ob-keys ob ob-eval
org-complete org-list org-faces org-compat org-entities org-macs
noutline outline cal-menu calendar cal-loaddefs bookmark pp recentf
tree-widget wid-edit savehist init-anything-thierry descbinds-anything
anything-ipython ipython python-mode info-look ansi-color executable
shell pcomplete shell-history anything-complete anything-show-completion
anything-obsolete anything-match-plugin anything-delicious
anything-mercurial anything-stgit anything-config browse-url rx xml url
url-proxy url-privacy url-expand url-methods url-history url-cookie
url-util url-parse url-vars mailcap grep compile comint ring tramp
tramp-compat format-spec tramp-loaddefs dired-aux ffap thingatpt
anything warnings epa-file epa derived epg epg-config auth-source eieio
byte-opt bytecomp byte-compile cconv macroexp assoc gnus-util time-date
mm-util mail-prsvr password-cache dired regexp-opt usage-memo punycode
idna naquadah-theme eev-thierry edmacro kmacro iterator eev-all
eev-mini-steps eev-browse-url eev-langs eev-compose eev-glyphs
disp-table eev-insert eev-steps eev-bounded eev easy-mmode advice
help-fns advice-preload w3m-wget preview-latex tex-site auto-loads info
easymenu cl tooltip ediff-hook vc-hooks lisp-float-type mwheel x-win
x-dnd tool-bar dnd fontset image fringe lisp-mode register page menu-bar
rfn-eshadow timer select scroll-bar mouse jit-lock font-lock syntax
facemenu font-core frame cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese hebrew greek romanian slovak
czech european ethiopic indian cyrillic chinese case-table epa-hook
jka-cmpr-hook help simple abbrev minibuffer loaddefs button faces
cus-face files text-properties overlay sha1 md5 base64 format env
code-pages mule custom widget hashtable-print-readable backquote
make-network-process dbusbind dynamic-setting system-font-setting
font-render-setting move-toolbar gtk x-toolkit x multi-tty emacs)

-- 
A+ Thierry
Get my Gnupg key:
gpg --keyserver pgp.mit.edu --recv-keys 59F29997 

Message #8 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Leo <sdl.web <at> gmail.com>
To: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Mon, 18 Jul 2011 14:24:19 +0800

On 2011-07-18 14:05 +0800, Thierry Volpiatto wrote:
> documentation return the list of arg for the defun*'s:(choose a short one)
>
> (documentation 'ert--remove*)
> "Does not support all the keywords of remove*.
>
> (fn X LIST &key KEY TEST)"
>
> It's annoying for function not documented because it return only list of
> args instead or returning nil.

Check the expansion of defun*; it always has a doc-string.

Leo

Message #11 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
To: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Mon, 18 Jul 2011 09:18:23 +0200

Leo <sdl.web <at> gmail.com> writes:

> On 2011-07-18 14:05 +0800, Thierry Volpiatto wrote:
>> documentation return the list of arg for the defun*'s:(choose a short one)
>>
>> (documentation 'ert--remove*)
>> "Does not support all the keywords of remove*.
>>
>> (fn X LIST &key KEY TEST)"
>>
>> It's annoying for function not documented because it return only list of
>> args instead or returning nil.
>
> Check the expansion of defun*; it always has a doc-string.
What expansion?

if you have:

--8<---------------cut here---------------start------------->8---
(defun* foo (&rest args) nil)
(documentation 'foo)
Give ==>
"

(fn &rest ARGS)"
--8<---------------cut here---------------end--------------->8---

which is wrong.

--8<---------------cut here---------------start------------->8---
(defun bar (&rest args) nil)
(documentation 'bar)
Give ==>nil
--8<---------------cut here---------------end--------------->8---

Which is correct.

-- 
A+ Thierry
Get my Gnupg key:
gpg --keyserver pgp.mit.edu --recv-keys 59F29997 

Message #14 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Leo <sdl.web <at> gmail.com>
To: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Mon, 18 Jul 2011 16:26:40 +0800

On 2011-07-18 15:18 +0800, Thierry Volpiatto wrote:
> (defun* foo (&rest args) nil)
> (documentation 'foo)
> Give ==>
> "
>
> (fn &rest ARGS)"

(defun* foo (&rest args) nil) is equivalent to

(defun foo
  (&rest args)
  "Not documented\n\n(fn &rest ARGS)"
  (let* nil
    (block foo nil)))

Leo

Message #17 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
To: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Mon, 18 Jul 2011 10:34:44 +0200

Leo <sdl.web <at> gmail.com> writes:

> On 2011-07-18 15:18 +0800, Thierry Volpiatto wrote:
>> (defun* foo (&rest args) nil)
>> (documentation 'foo)
>> Give ==>
>> "
>>
>> (fn &rest ARGS)"
>
> (defun* foo (&rest args) nil) is equivalent to
>
> (defun foo
>   (&rest args)
>   "Not documented\n\n(fn &rest ARGS)"
>   (let* nil
>     (block foo nil)))
So it should return:
"Not documented

(fn &rest ARGS)"

-- 
A+ Thierry
Get my Gnupg key:
gpg --keyserver pgp.mit.edu --recv-keys 59F29997 

Message #20 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Mon, 18 Jul 2011 12:02:26 -0400

> documentation return the list of arg for the defun*'s:(choose a short one)

> --8<---------------cut here---------------start------------->8---
> (documentation 'ert--remove*)
> "Does not support all the keywords of remove*.

> (fn X LIST &key KEY TEST)"
> --8<---------------cut here---------------end--------------->8---

> It's annoying for function not documented because it return only list of
> args instead or returning nil.

Yes, it's a bit inconvenient.  But if you don't want the arglist, you
should pass the output of documentation through help-split-fundoc.
That should then return you the nil you're looking for.


        Stefan

Message #23 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Mon, 18 Jul 2011 19:51:39 +0200

Thierry Volpiatto <thierry.volpiatto <at> gmail.com> writes:

> (defun* foo (&rest args) nil)
> (documentation 'foo)
> Give ==>
> "
>
> (fn &rest ARGS)"
>
> which is wrong.

Why is that wrong?  You need the signature to properly display the
original argument list.

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Message #26 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Tue, 19 Jul 2011 08:06:39 +0200

Hello,

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>> documentation return the list of arg for the defun*'s:(choose a short one)
>
>> --8<---------------cut here---------------start------------->8---
>> (documentation 'ert--remove*)
>> "Does not support all the keywords of remove*.
>
>> (fn X LIST &key KEY TEST)"
>> --8<---------------cut here---------------end--------------->8---
>
>> It's annoying for function not documented because it return only list of
>> args instead or returning nil.
>
> Yes, it's a bit inconvenient.  But if you don't want the arglist, you
> should pass the output of documentation through help-split-fundoc.
> That should then return you the nil you're looking for.
The cdr of help-split-fundoc return nil as expected for functions, CL-style
function, but always nil for macros even if they are documented.

Thus the docstring seem wrong, as it say it return nil if not
documented, which is wrong because it return a one arg list
in this case.

I had expected documentation has the same behavior for functions,
CL-style functions, and macros.

And it seem describe-function-1 is a long function that have to deal
with these inconveniences.

-- 
A+ Thierry
Get my Gnupg key:
gpg --keyserver pgp.mit.edu --recv-keys 59F29997 

Message #29 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50; `documentation' should not return args list for
	CL defun*.
Date: Mon, 01 Aug 2011 17:33:17 -0400

>> Yes, it's a bit inconvenient.  But if you don't want the arglist, you
>> should pass the output of documentation through help-split-fundoc.
>> That should then return you the nil you're looking for.
> The cdr of help-split-fundoc return nil as expected for functions, CL-style
> function, but always nil for macros even if they are documented.

Hmm... I don't understand: help-split-fundoc doesn't care if the
docstring comes from a function, a macro, or a mushroom.  Or maybe
I don't understand what you're saying.  Can you show some detail of what
you do?


        Stefan

Message #32 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Tue, 02 Aug 2011 07:21:15 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>>> Yes, it's a bit inconvenient.  But if you don't want the arglist, you
>>> should pass the output of documentation through help-split-fundoc.
>>> That should then return you the nil you're looking for.
>> The cdr of help-split-fundoc return nil as expected for functions, CL-style
>> function, but always nil for macros even if they are documented.
>
> Hmm... I don't understand: help-split-fundoc doesn't care if the
> docstring comes from a function, a macro, or a mushroom.  Or maybe
> I don't understand what you're saying.  Can you show some detail of what
> you do?

--8<---------------cut here---------------start------------->8---
(defun* foo (&rest args) nil)
(help-split-fundoc (documentation 'foo) nil)
=>("(nil &rest ARGS)")

(defun bar (&rest args) nil)
(help-split-fundoc (documentation 'bar) nil)
=>nil

(defmacro foo-1 (&rest args) "some doc." nil)
(help-split-fundoc (documentation 'foo-1) nil)
nil
--8<---------------cut here---------------end--------------->8---

But same here, it's ok i finally parse myself th output of documentation
to extract the first line, it works fine.(so i don't use
help-split-fundoc)


-- 
A+ Thierry
Get my Gnupg key:
gpg --keyserver pgp.mit.edu --recv-keys 59F29997 

Message #35 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50; `documentation' should not return args list for
	CL defun*.
Date: Tue, 02 Aug 2011 15:16:19 -0400

> (defun* foo (&rest args) nil)
> (help-split-fundoc (documentation 'foo) nil)
> =>("(nil &rest ARGS)")

> (defun bar (&rest args) nil)
> (help-split-fundoc (documentation 'bar) nil)
> =>nil

> (defmacro foo-1 (&rest args) "some doc." nil)
> (help-split-fundoc (documentation 'foo-1) nil)
> nil

Right, as explained in help-split-fundoc's docstring:

   Return (USAGE . DOC) or nil if there's no usage info.

So if you just want the docstring, you'll need something like

  (let ((doc (documentation bidule)))
    (or (cdr (help-split-fundoc doc nil)) doc))

I agree this is not super convenient.


        Stefan

Message #38 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Tue, 02 Aug 2011 21:43:43 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>> (defun* foo (&rest args) nil)
>> (help-split-fundoc (documentation 'foo) nil)
>> =>("(nil &rest ARGS)")
>
>> (defun bar (&rest args) nil)
>> (help-split-fundoc (documentation 'bar) nil)
>> =>nil
>
>> (defmacro foo-1 (&rest args) "some doc." nil)
>> (help-split-fundoc (documentation 'foo-1) nil)
>> nil
>
> Right, as explained in help-split-fundoc's docstring:
>
>    Return (USAGE . DOC) or nil if there's no usage info.
>
> So if you just want the docstring, you'll need something like
>
>   (let ((doc (documentation bidule)))
>     (or (cdr (help-split-fundoc doc nil)) doc))
>
> I agree this is not super convenient.
Yes, i think i have tried that, but it doesn't return nil for the case
of CL-style functions.

What i wanted was return only the first line of docstring or nil or "not
documented" if no docstring.
(to display in mode-line when completing lisp symbols)

Here what i use finally:


#+BEGIN_SRC lisp
(defun anything-c-get-first-line-documentation (sym)
  "Return first line documentation of symbol SYM.
If SYM is not documented, return \"Not documented\"."
  (let ((doc (cond ((fboundp sym)
                    (documentation sym t))
                   ((boundp sym)
                    (documentation-property sym 'variable-documentation t))
                   ((facep sym)
                    (face-documentation sym))
                   (t nil))))
    (if (and doc (not (string= doc ""))
             ;; `documentation' return "\n\n(args...)"
             ;; for CL-style functions.
             (not (string-match-p "^\n\n" doc)))
        (car (split-string doc "\n"))
        "Not documented")))

#+END_SRC


-- 
A+ Thierry
Get my Gnupg key:
gpg --keyserver pgp.mit.edu --recv-keys 59F29997 

Message #41 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Tue, 02 Aug 2011 16:31:59 -0400

>> (let ((doc (documentation bidule)))
>>   (or (cdr (help-split-fundoc doc nil)) doc))
>> I agree this is not super convenient.
> Yes, i think i have tried that, but it doesn't return nil for the case
> of CL-style functions.

In Emacs-24, it returns nil if the function had no docstring (the CL or
non-CL distinction is a only indirectly linked to the problem).  So the
above should return either:
- the full docstring if there's one.
- nil or the empty string or "Not documented" if there isn't any docstring.
So if you want the first line, just extract it from the output when it's
not nil.


        Stefan

Message #44 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Tue, 02 Aug 2011 22:50:18 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>>> (let ((doc (documentation bidule)))
>>>   (or (cdr (help-split-fundoc doc nil)) doc))
>>> I agree this is not super convenient.
>> Yes, i think i have tried that, but it doesn't return nil for the case
>> of CL-style functions.
>
> In Emacs-24, it returns nil if the function had no docstring (the CL or
> non-CL distinction is a only indirectly linked to the problem).  So the
> above should return either:
> - the full docstring if there's one.
> - nil or the empty string or "Not documented" if there isn't any
> docstring.
No, it doesn't, it return for example for: (I use emacs24)

(defun* foo (&rest args) nil)
=> "nil (&rest args)"

and for most not documented CL-style functions:
=> "\n\n (args...)"

But neither nil, empty string or "not documented".

See comment in function i sent.

> So if you want the first line, just extract it from the output when it's
> not nil.
Problem it's not non--nil.(except for elisp function of course)


-- 
A+ Thierry
Get my Gnupg key:
gpg --keyserver pgp.mit.edu --recv-keys 59F29997 

Message #47 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Tue, 02 Aug 2011 21:16:49 -0400

>>>> (let ((doc (documentation bidule)))
>>>> (or (cdr (help-split-fundoc doc nil)) doc))
>>>> I agree this is not super convenient.
>>> Yes, i think i have tried that, but it doesn't return nil for the case
>>> of CL-style functions.
>> 
>> In Emacs-24, it returns nil if the function had no docstring (the CL or
>> non-CL distinction is a only indirectly linked to the problem).  So the
>> above should return either:
>> - the full docstring if there's one.
>> - nil or the empty string or "Not documented" if there isn't any
>> docstring.
> No, it doesn't, it return for example for: (I use emacs24)

Oh, you're right:

  (let* ((doc (documentation bidule))
         (split (help-split-fundoc doc nil)))
    (if split (cdr split) doc))

might work better.  Still, you should be able to get the right code by
reading the docstring and trying things out.


-- Stefan

Message #50 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Wed, 03 Aug 2011 07:10:04 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

>>>>> (let ((doc (documentation bidule)))
>>>>> (or (cdr (help-split-fundoc doc nil)) doc))
>>>>> I agree this is not super convenient.
>>>> Yes, i think i have tried that, but it doesn't return nil for the case
>>>> of CL-style functions.
>>> 
>>> In Emacs-24, it returns nil if the function had no docstring (the CL or
>>> non-CL distinction is a only indirectly linked to the problem).  So the
>>> above should return either:
>>> - the full docstring if there's one.
>>> - nil or the empty string or "Not documented" if there isn't any
>>> docstring.
>> No, it doesn't, it return for example for: (I use emacs24)
>
> Oh, you're right:
>
>   (let* ((doc (documentation bidule))
>          (split (help-split-fundoc doc nil)))
>     (if split (cdr split) doc))
Yes, thanks, that's usable.
But it add unnecessary complications for same result, so for the moment
i will use my original code that is simpler and shorter.

> might work better.  Still, you should be able to get the right code by
> reading the docstring and trying things out.
Docstring is hard to understand.
The term "usage" in docstring is not understandable until trying out the
function and see results after evaluation.
Idem for "def" argument.

Thanks for helping on that.

-- 
A+ Thierry
Get my Gnupg key:
gpg --keyserver pgp.mit.edu --recv-keys 59F29997 

Message #53 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Wed, 03 Aug 2011 10:31:19 -0400

severity 9115 wishlist
retitle 9115 `documentation' should let you choose whether to include `usage'
thanks

>> (let* ((doc (documentation bidule))
>> (split (help-split-fundoc doc nil)))
>> (if split (cdr split) doc))
> Yes, thanks, that's usable.
> But it add unnecessary complications for same result, so for the moment
> i will use my original code that is simpler and shorter.

Yes, as mentioned earlier, I'm not particularly proud of the gymnastic
you have to go through to get what you want.

>> might work better.  Still, you should be able to get the right code by
>> reading the docstring and trying things out.
> Docstring is hard to understand.
> The term "usage" in docstring is not understandable until trying out the
> function and see results after evaluation.

Ah, I see the problem now.  Would the patch below have helped?

> Idem for "def" argument.

Not sure how I can improve this part.


        Stefan


=== modified file 'lisp/help-fns.el'
--- lisp/help-fns.el	2011-06-28 17:20:41 +0000
+++ lisp/help-fns.el	2011-08-03 14:29:40 +0000
@@ -102,7 +102,8 @@
 
 (defun help-split-fundoc (docstring def)
   "Split a function DOCSTRING into the actual doc and the usage info.
-Return (USAGE . DOC) or nil if there's no usage info.
+Return (USAGE . DOC) or nil if there's no usage info, where USAGE info
+is a string such as \"(apply FUNCTION &rest ARGUMENTS)\".
 DEF is the function whose usage we're looking for in DOCSTRING."
   ;; Functions can get the calling sequence at the end of the doc string.
   ;; In cases where `function' has been fset to a subr we can't search for

Message #60 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50;
	`documentation' should not return args list for CL defun*.
Date: Wed, 03 Aug 2011 16:45:46 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> Ah, I see the problem now.  Would the patch below have helped?
Yes, better.
Here what i have in my help buffer of help-split-fundoc:

--8<---------------cut here---------------start------------->8---
USAGE= liste des arguments de la fonction.
DOC=   Docstring de la fonction.
DEF= dans la liste des arguments (USAGE), on va avoir:
"(DEF arg1 arg2 ...)"
Si DEF est nil on aura:
"(nil arg1 arg2...)"
Autrement:
"(DEF_name arg1 arg2...)"

Exemples:
[...]
--8<---------------cut here---------------end--------------->8---

>> Idem for "def" argument.
>
> Not sure how I can improve this part.
>
>
>         Stefan
>
>
> === modified file 'lisp/help-fns.el'
> --- lisp/help-fns.el	2011-06-28 17:20:41 +0000
> +++ lisp/help-fns.el	2011-08-03 14:29:40 +0000
> @@ -102,7 +102,8 @@
>  
>  (defun help-split-fundoc (docstring def)
>    "Split a function DOCSTRING into the actual doc and the usage info.
> -Return (USAGE . DOC) or nil if there's no usage info.
> +Return (USAGE . DOC) or nil if there's no usage info, where USAGE info
> +is a string such as \"(apply FUNCTION &rest ARGUMENTS)\".
>  DEF is the function whose usage we're looking for in DOCSTRING."
>    ;; Functions can get the calling sequence at the end of the doc string.
>    ;; In cases where `function' has been fset to a subr we can't search for
>

-- 
A+ Thierry
Get my Gnupg key:
gpg --keyserver pgp.mit.edu --recv-keys 59F29997 

Message #63 received at 9115 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Thierry Volpiatto <thierry.volpiatto <at> gmail.com>
Cc: Stefan Monnier <monnier <at> iro.umontreal.ca>, 9115 <at> debbugs.gnu.org
Subject: Re: bug#9115: 24.0.50; `documentation' should not return args list
 for CL defun*.
Date: Sat, 12 Oct 2019 07:02:24 +0200

Thierry Volpiatto <thierry.volpiatto <at> gmail.com> writes:

>> Ah, I see the problem now.  Would the patch below have helped?
> Yes, better.

I think the conclusion here was that nothing further seemed likely to be
done here with this issue, so I'm closing this bug report now.

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.