From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: Re: Automated docstring testing Date: Wed, 20 May 2015 14:47:56 -0400 Message-ID: References: <87d21vqqqf.fsf@gmail.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1432147743 9215 80.91.229.3 (20 May 2015 18:49:03 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 20 May 2015 18:49:03 +0000 (UTC) Cc: emacs-devel@gnu.org To: Oleh Krehel Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed May 20 20:48:56 2015 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 1Yv931-0008J3-Jf for ged-emacs-devel@m.gmane.org; Wed, 20 May 2015 20:48:55 +0200 Original-Received: from localhost ([::1]:53701 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Yv930-0001oJ-Vm for ged-emacs-devel@m.gmane.org; Wed, 20 May 2015 14:48:55 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39960) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Yv92C-0000vc-QR for emacs-devel@gnu.org; Wed, 20 May 2015 14:48:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Yv928-000881-Ls for emacs-devel@gnu.org; Wed, 20 May 2015 14:48:04 -0400 Original-Received: from pruche.dit.umontreal.ca ([132.204.246.22]:48694) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Yv928-00087h-HR for emacs-devel@gnu.org; Wed, 20 May 2015 14:48:00 -0400 Original-Received: from ceviche.home (lechon.iro.umontreal.ca [132.204.27.242]) by pruche.dit.umontreal.ca (8.14.1/8.14.1) with ESMTP id t4KIluix010089; Wed, 20 May 2015 14:47:56 -0400 Original-Received: by ceviche.home (Postfix, from userid 20848) id BBD3F66092; Wed, 20 May 2015 14:47:56 -0400 (EDT) In-Reply-To: <87d21vqqqf.fsf@gmail.com> (Oleh Krehel's message of "Wed, 20 May 2015 16:16:08 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux) X-NAI-Spam-Flag: NO X-NAI-Spam-Threshold: 5 X-NAI-Spam-Score: 0 X-NAI-Spam-Rules: 1 Rules triggered RV5312=0 X-NAI-Spam-Version: 2.3.0.9393 : core <5312> : inlines <3041> : streams <1441900> : uri <1935546> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 132.204.246.22 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:186674 Archived-At: > As I was just editing subr.el, I noticed that some functions there are > missing a docstring, and a lot of them don't conform to `checkdoc'. > I attach a patch that makes it possible to call: > make checkdoc Looks like a good idea, but it's going to take some work to make it usable: we'll need to tweak checkdoc to remove some of the things it complains about (e.g. the preference for "-flag" for boolean vars, with which I simply disagree) otherwise the output is just much too long and will never get fixed. IOW it should only include the things which we really always want to fix. Things like args not being mentioned in the docstring aren't always actual bugs, so we shouldn't complain about them (e.g. for interactive-only functions, the docstring often is written from the interactive-user's point of view, so it should talk about the region and the C-u prefix rather than about the function's own arguments). Or else we need to add some (lightweight/concise) way to silence those complaints on a case-by-case basis. These would be good changes regardless of this particular make target, of course. > I'm not yet sure if the file list should be passed to `make', or it > should be hard-coded, so far I've just put '("subr.el") as the > file list. Good question. > I also don't know where to put a file that the Makefile target wants to > load, I've just put it in lisp/do-checkdoc.el. If it's short, you can put the Elisp code inline in the Makefile. Else you can put it in the `admin' subdirectory. Putting it in `lisp' is probably not a good idea, unless it can be used by unbundled Elisp packages. Another option is to put the code in checkdoc.el. Stefan