From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Juanma Barranquero Newsgroups: gmane.emacs.devel Subject: CL function's docstrings Date: Tue, 17 May 2005 01:52:06 +0200 Message-ID: Reply-To: Juanma Barranquero NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable X-Trace: sea.gmane.org 1116363825 5432 80.91.229.2 (17 May 2005 21:03:45 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Tue, 17 May 2005 21:03:45 +0000 (UTC) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue May 17 23:03:40 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1DY9BP-0006cD-4n for ged-emacs-devel@m.gmane.org; Tue, 17 May 2005 23:00:55 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1DY9Dh-0007sa-SX for ged-emacs-devel@m.gmane.org; Tue, 17 May 2005 17:03:17 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1DXqAn-0005OD-50 for emacs-devel@gnu.org; Mon, 16 May 2005 20:43:01 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1DXpqK-0000qE-6q for emacs-devel@gnu.org; Mon, 16 May 2005 20:21:52 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1DXpoN-0000Ov-Vy for emacs-devel@gnu.org; Mon, 16 May 2005 20:19:52 -0400 Original-Received: from [64.233.184.198] (helo=wproxy.gmail.com) by monty-python.gnu.org with esmtp (Exim 4.34) id 1DXpVD-0006LU-7Z for emacs-devel@gnu.org; Mon, 16 May 2005 20:00:03 -0400 Original-Received: by wproxy.gmail.com with SMTP id 50so2163127wri for ; Mon, 16 May 2005 16:52:08 -0700 (PDT) DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws; s=beta; d=gmail.com; h=received:message-id:date:from:reply-to:to:subject:mime-version:content-type:content-transfer-encoding:content-disposition; b=UzbMqNYj05Nqt8bXzfOxLlmfvSqbvAS4CWoWqmy5yEXCLL/I2OlXdphaO0HrCoBPCWYFEPw4Ygvv2mm6q2aSuM5sG7JY4ceyQV9Soi2fspoYEOOnw+UitbF8HadtX184PdBspF3zJxa/K4Whn/vDqJIEPDVX6Msl2zcqJepzXRc= Original-Received: by 10.54.51.45 with SMTP id y45mr3954847wry; Mon, 16 May 2005 16:52:08 -0700 (PDT) Original-Received: by 10.54.82.6 with HTTP; Mon, 16 May 2005 16:52:06 -0700 (PDT) Original-To: emacs-devel@gnu.org Content-Disposition: inline X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:37191 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:37191 Many cl*.el functions have a mismatch between the real argument names and the ones used in their docstrings (mostly because many cl functions do use some kind of old "standardized" naming scheme for arguments, like cl-env, cl-keys, etc.). For example, `cl-macroexpand' uses cl-macro and cl-env as arguments, but FORM and ENVIRONMENT on the docstring. Unfortunately, this makes `describe-function' less than useful for these functions (and defeats argument highlighting). AFAICS, there are four possible answers: 1) Do nothing. The easier, if uglier, way :) 2) Change the argument names to match the docstrings. Pros: it is the cleaner way. Cons: lot of change in the cl* files; less coherence between argument = names among functions. 3) Change the docstrings to match the argument names. Pro: easy. Cons: names are often much less descriptive than the ones already exis= ting. 4) Add \(fn ARG1 ARG2...) sections to docstrings. Pro: better info in `describe-function'; little change (one fn line + one blank line per function's docstring, at most). Cons: many functions will need this, and \(fn ARG) forms are uglier and more difficult to maintain. I personally gravitate towards 2) or 4). Does anyone else have an opinion about the issue? --=20 /L/e/k/t/u