GNU bug report logs - #7521
24.0.50; doc for `delimit-columns-*'

Previous Next

Full log

View this message in rfc822 format

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Lars Magne Ingebrigtsen'" <larsi <at> gnus.org>
Cc: 7521 <at> debbugs.gnu.org
Subject: bug#7521: 24.0.50; doc for `delimit-columns-*'
Date: Sat, 2 Jul 2011 08:21:40 -0700

> > 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.

Previous Next

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