From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Xue Fuqiao Newsgroups: gmane.emacs.devel Subject: Re: Changes in revision 114466 Date: Mon, 30 Sep 2013 12:55:47 +0800 Message-ID: References: <831u49fkxk.fsf@gnu.org> <83pprse4mf.fsf@gnu.org> <87ioxk3x9z.fsf@zigzag.favinet> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 X-Trace: ger.gmane.org 1380516949 17930 80.91.229.3 (30 Sep 2013 04:55:49 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 30 Sep 2013 04:55:49 +0000 (UTC) Cc: emacs-devel To: Thien-Thi Nguyen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Sep 30 06:55:54 2013 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1VQVWU-0008Lg-C7 for ged-emacs-devel@m.gmane.org; Mon, 30 Sep 2013 06:55:54 +0200 Original-Received: from localhost ([::1]:46836 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQVWT-0007oA-Vm for ged-emacs-devel@m.gmane.org; Mon, 30 Sep 2013 00:55:53 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39717) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQVWR-0007o3-RQ for emacs-devel@gnu.org; Mon, 30 Sep 2013 00:55:52 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VQVWQ-0006zq-UU for emacs-devel@gnu.org; Mon, 30 Sep 2013 00:55:51 -0400 Original-Received: from mail-ie0-x229.google.com ([2607:f8b0:4001:c03::229]:34673) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VQVWP-0006zY-6J; Mon, 30 Sep 2013 00:55:49 -0400 Original-Received: by mail-ie0-f169.google.com with SMTP id tp5so9107095ieb.14 for ; Sun, 29 Sep 2013 21:55:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type; bh=JGqEKlkTv+jspy4RiaDuku+LRLFrG8vFkhX+gvR47D4=; b=XbTJB4oEmtkudbs4CE9i3++XX8txWj+mil9xKaAHSCdwZhaZW7IH4XUJeW2KCjCS5r +8AzLJiHprjOoxY3pXTPYFN7+9IGnFk2Md8YynxK6laiodApEEzAWMKLCV9mChjAb5Io 9i2vZ8XtBudYZunyLUUVbRitRbZVe/nR5vBQLEm7AtzqpVr94xHqlf/VeFnwQiH/7KuZ mE7rC0uNdSyM7NVWpVnN5y9gVmSmxeRndoJQyLFjdU6+00QakbjUTcSVcPBnMO42gZcu vKZbg++EFMCgOyNACkZGABAYTpE+IXIBLZbz9/0LTXq0AJEh5yNvhCW9rO1ABLUGu6SW 5uig== X-Received: by 10.50.115.100 with SMTP id jn4mr12434043igb.9.1380516947828; Sun, 29 Sep 2013 21:55:47 -0700 (PDT) Original-Received: by 10.42.133.72 with HTTP; Sun, 29 Sep 2013 21:55:47 -0700 (PDT) In-Reply-To: <87ioxk3x9z.fsf@zigzag.favinet> X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2607:f8b0:4001:c03::229 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:163721 Archived-At: On Sun, Sep 29, 2013 at 3:24 PM, Thien-Thi Nguyen wrote: > () Eli Zaretskii > () Sun, 29 Sep 2013 05:36:08 +0300 > > > >> +@c FIXME: Document these functions: > > >> +@c `bool-vector-exclusive-or' > > >> +@c `bool-vector-union' > > >> +@c `bool-vector-intersection' > > >> +@c `bool-vector-set-difference' > > >> +@c `bool-vector-not' > > >> +@c `bool-vector-subset' > > >> +@c `bool-vector-count-matches' > > >> +@c `bool-vector-count-matches-at' > > Nothing to be sorry about, and thank you. > > If the names of these functions were produced by some scanning program, > this is a good opportunity to add that code to the repo (under admin/). > > If they were produced by hand, then i guess the zeroth step would be to > write a program that likewise produces them. > > The overall meta-goals are to make doc coverage easy to determine for > everyone, and to render the selection criteria (for surely, some things > do not warrant "full" documentation) explicit and consequently subject > to refinement. > > With this in place, the overall goal of improving the doc coverage is > most easily realizable, not just once, but also as an ongoing basis, as > Emacs gains new features over time. Agreed. The name of these functions were produced by hand. To make doc coverage, the only solution that I see is scanning the Emacs repo for keywords like these: (def\\(var\\|const\\|custom\\) (def\\(un\\|subst\\|macro\\|advice\\) (def\\(type\\|struct\\|class\\|ine-condition\\) DEFUN (" maybe also for defgroup, defmath, defalias, cl-{defun, defmacro, defsubst}, ... although `defadvice' should not be used for Lisp code in Emacs proper. But I see one problem: not every {functions, variables, ...} needs documenting. E.g., some functions/variables use two hyphens to separate prefix. These functions/variables usually don't needs documenting. IMO every user option and every command needs documentation. -- Best regards, Xue Fuqiao. http://www.gnu.org/software/emacs/