From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Improving documentation for ert.el. Date: Thu, 15 Aug 2024 11:32:36 +0300 Message-ID: <86plqa6va3.fsf@gnu.org> References: Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="13991"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: rms@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Thu Aug 15 10:33:51 2024 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1seVvb-0003So-Dv for ged-emacs-devel@m.gmane-mx.org; Thu, 15 Aug 2024 10:33:51 +0200 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1seVun-0004Rw-Hd; Thu, 15 Aug 2024 04:33:01 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1seVul-0004Rh-3N for emacs-devel@gnu.org; Thu, 15 Aug 2024 04:32:59 -0400 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1seVue-0005Zr-Ms for emacs-devel@gnu.org; Thu, 15 Aug 2024 04:32:58 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=eYg8FMxub9bLHAtmsK5cS/+/DS8axbDNwKy2kqJXtus=; b=E78urDVGf2qn t/r55LzSXrPEUcvk4pvCu3QFWVvARzq9kCg+WKcCY7LzbOVR8FWazGithSnze2VxrVm2SkgxKeq+q 0GfDQ0JxKoTXjmE20eQllA9ETtEV/IowsR3PfUJXBeJmv93vTur9UBxV8vLipziCnUAGmyCG1ws+g mMfF7prlC9UtpHPV1zlfgRFyQh712pT/skjUlpbhEoSM6Bs5XHzyo0orye2CxZR8a5+xzXFlX4wsR YkC5wExu0hGEyQK+U+Cjn6eUQroSQBxO3b3m18mRHxV3FF06NWMfThKdH8yN9yrgudGFuI2kE3qRI IUc3mJU+D0id+Mb/Mwngvg==; In-Reply-To: (message from Richard Stallman on Sat, 10 Aug 2024 22:10:20 -0400) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 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-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:322772 Archived-At: > From: Richard Stallman > Date: Sat, 10 Aug 2024 22:10:20 -0400 > > I started to write tests for `cond*', and found that the documentation > in ert.el was unjelpful about how to run the test I had written. ERT has its own manual, ert.info. I suggest to read it when the doc strings are insufficient, and definitely before you fall back on reading the comments in ert.el -- that is NOT the primary source of the documentation for users of ert.el. > I read the comment at the beginning, which told me about > `ert-run-tests-interactively'. But what argument should I use? The > doc string of `ert-run-tests-interactively' referred me to > `ert-select-tests'. The ERT manual describes this command in "Running Tests Interactively", and has a cross-reference to "Test Selectors" where the argument is described. But for most purposes, just accepting the default argument of 't' (which means to run all tests) is what you usually want. > The doc string of `ert-select-tests' is abstract, and may be helpful > for understanding how its code works, but it is no help for a user > trying to see how to call `ert-run-tests-interactively' for any > specific case. The node "Test Selectors" in the ERT manual is more helpful, I think. > I that the name defined with `ert-deftest' would have something to do > with a name to specify, but was it the symbol itself or its value or > somehing else? Since the comments did not say, I tried them but > confusion got in the way. Eventually, after I started writing this, I > tried again and that that name did work right when passed to > `ert-run-tests-interactively'. > > I think the documentation should say this very explicitly, at the top > of the file, and in `ert-run-tests-interactively', and also in > `ert-select-tests'. This will be small compared with the size of > ert.el. I clarified some of the related doc strings and the ERT manual on the emacs-30 branch.