From: "Drew Adams" <drew.adams@oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi@gnus.org>
Cc: 7521@debbugs.gnu.org
Subject: bug#7521: 24.0.50; doc for `delimit-columns-*'
Date: Sat, 2 Jul 2011 08:21:40 -0700 [thread overview]
Message-ID: <06B232927CEE40FC91F8398F1EFDDF97@us.oracle.com> (raw)
In-Reply-To: <m3hb74ssoy.fsf@quimbies.gnus.org>
> > You cannot understand a thing about commands
> > `delimit-columns-region' and `delimit-columns-rectangle'
> > without reading the commentary in Lisp
> > file delim-col.el. In sum, there is no help for users - no doc.
>
> I suspect that the workings of delim-col.el are too complicated to be
> explained in a doc string for any of the commands. If these commands
> are to be useful to users, I think the proper solution is to document
> them in the elisp manual.
You might be right; I really don't know. My take is that these things are
explained in the source-code comments, and that this info needs to be made
available to users via help/doc. If the details get transferred to the manual,
OK.
But even then the doc strings of the various functions (these are user
_commands_, after all) need to give some explanation. If we cannot explain
these commands at all then maybe that's a sign that the commands themselves are
overly complex.
A user should be able to get some idea of what to expect from a command by
reading its doc string. That s?he might need to consult the manual for more
detail is fine. But that's not a reason to have incomprehensible or vacuous doc
strings.
next prev parent reply other threads:[~2011-07-02 15:21 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-11-30 19:34 bug#7521: 24.0.50; doc for `delimit-columns-*' Drew Adams
2011-07-02 13:44 ` Lars Magne Ingebrigtsen
2011-07-02 15:21 ` Drew Adams [this message]
2011-07-02 15:34 ` Lars Magne Ingebrigtsen
2011-07-02 15:59 ` Drew Adams
2011-07-02 16:10 ` Lars Magne Ingebrigtsen
2011-07-02 16:28 ` Drew Adams
2011-07-02 16:30 ` Lars Magne Ingebrigtsen
2011-07-02 16:32 ` Drew Adams
2011-07-04 1:08 ` Stefan Monnier
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=06B232927CEE40FC91F8398F1EFDDF97@us.oracle.com \
--to=drew.adams@oracle.com \
--cc=7521@debbugs.gnu.org \
--cc=larsi@gnus.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.