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: Docstrings and manuals Date: Mon, 18 Apr 2016 15:33:20 -0400 Message-ID: References: <6ok2vyzwf9.fsf@fencepost.gnu.org> <08f70cda-44be-0657-e50a-2b2c80d2c21c@yandex.ru> <87oa9dzgl0.fsf@gmx.de> <87potshczh.fsf@gmx.de> <87h9f4ghzg.fsf@gmx.de> <8737qnc8ep.fsf@gmx.de> <87k2jwd3gr.fsf_-_@gmx.de> <8dfdfe5d-41fe-7c05-0054-0bd3e589390e@yandex.ru> <8737qkcwoo.fsf@gmx.de> <909c91ef-aa2e-4bcc-9828-603c4203e3d0@yandex.ru> <83ziss9sml.fsf@gnu.org> <878u0bcc0b.fsf@russet.org.uk> <831t62agqc.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1461008012 23058 80.91.229.3 (18 Apr 2016 19:33:32 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 18 Apr 2016 19:33:32 +0000 (UTC) Cc: emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Apr 18 21:33:17 2016 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 1asEv6-0003WP-It for ged-emacs-devel@m.gmane.org; Mon, 18 Apr 2016 21:33:16 +0200 Original-Received: from localhost ([::1]:44229 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1asEv5-0003Uw-Vk for ged-emacs-devel@m.gmane.org; Mon, 18 Apr 2016 15:33:15 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46916) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1asEv1-0003Ra-UA for emacs-devel@gnu.org; Mon, 18 Apr 2016 15:33:12 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1asEuy-00051S-Nd for emacs-devel@gnu.org; Mon, 18 Apr 2016 15:33:11 -0400 Original-Received: from chene.dit.umontreal.ca ([132.204.246.20]:51701) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1asEuy-0004zc-Ho; Mon, 18 Apr 2016 15:33:08 -0400 Original-Received: from ceviche.home (lechon.iro.umontreal.ca [132.204.27.242]) by chene.dit.umontreal.ca (8.14.7/8.14.7) with ESMTP id u3IJWcgh025158; Mon, 18 Apr 2016 15:32:39 -0400 Original-Received: by ceviche.home (Postfix, from userid 20848) id F1E1A662C5; Mon, 18 Apr 2016 15:33:20 -0400 (EDT) In-Reply-To: <831t62agqc.fsf@gnu.org> (Eli Zaretskii's message of "Mon, 18 Apr 2016 21:56:11 +0300") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.1.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 RV5646=0 X-NAI-Spam-Version: 2.3.0.9418 : core <5646> : inlines <4688> : streams <1621482> : uri <2190748> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 132.204.246.20 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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" Xref: news.gmane.org gmane.emacs.devel:203066 Archived-At: >> FWIW, I like this idea. I think we could reduce the amount of >> "reference info" in the manual (a part that's already available in the >> docstrings) by referring to the docstring instead, and instead increase >> the amount of explanation giving tips/examples about how to use it. > Then the manual will be a very awkward reading, even on-line. Maybe we could just change the manual so it's not as complete-and-definitive, but it's still self-standing (tho with easy ways to get more details via docstrings). > To say nothing of the fact that the current doc strings are usually > much worse than the documentation in the manual. Docstrings should (ideally) always be as complete as the manual, in the sense that the actual info is there. In practice, I find it's usually the case. But it's often present in a much rougher shape, indeed, so you can only figure out that info after reading the manual to figure out what the docstring really means. > IOW, let's first make sure every changeset is accompanied by good > documentation, and only then consider such significant changes. Agreed, Stefan