From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Dmitry Gutov Newsgroups: gmane.emacs.devel Subject: Re: Docstrings and manuals Date: Sun, 17 Apr 2016 16:12:05 +0300 Message-ID: <149a61a2-d812-5ae1-d969-d4201872e870@yandex.ru> 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> <87y48cctr6.fsf@gmx.de> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1460898746 10267 80.91.229.3 (17 Apr 2016 13:12:26 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 17 Apr 2016 13:12:26 +0000 (UTC) Cc: Glenn Morris , emacs-devel To: Michael Albinus Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Apr 17 15:12:19 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 1armUs-0004V8-TC for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 15:12:19 +0200 Original-Received: from localhost ([::1]:45971 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1armUs-0004uh-0v for ged-emacs-devel@m.gmane.org; Sun, 17 Apr 2016 09:12:18 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:32901) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1armUo-0004s8-J8 for emacs-devel@gnu.org; Sun, 17 Apr 2016 09:12:15 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1armUl-0000u4-Bu for emacs-devel@gnu.org; Sun, 17 Apr 2016 09:12:14 -0400 Original-Received: from mail-wm0-x244.google.com ([2a00:1450:400c:c09::244]:35593) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1armUl-0000sx-5I; Sun, 17 Apr 2016 09:12:11 -0400 Original-Received: by mail-wm0-x244.google.com with SMTP id a140so17608937wma.2; Sun, 17 Apr 2016 06:12:11 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:subject:to:references:cc:from:message-id:date:user-agent :mime-version:in-reply-to:content-transfer-encoding; bh=1mcxuAUfWOYJYYDLZ8UADOR7MtI7xM8t6btvlgVZU4s=; b=WoS6CATe170cvmxyz8dKD/id92MnZJ8zSNvUS5VQ80mJPb/SiPqEk4hUOq1Xz49+3b /KKb9uS50DV8sba2/CpNAVLGcZqeyZInuodcUMp3ryifRThnteZvEiqdUD4Za7imInFH 9+sOi+3B/MoBeqEWljpMnIAuA+VxrAI/TIRVBuQO3WFTsoOlg9Uzm7+YzbMrTsAwEY67 KNbT6enT55RdhNiuWaDmsl9MhPP/XarnMpBbNCP8E6q6ps6UA3xO6Na01YFI7ZSywp/h w0X6eXosVXMK/6X50c3SzSnKrE421Vul66F+C1GFM8wH8HQOzK430jbXmBBWSn67Xe3L 9D0A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:sender:subject:to:references:cc:from:message-id :date:user-agent:mime-version:in-reply-to:content-transfer-encoding; bh=1mcxuAUfWOYJYYDLZ8UADOR7MtI7xM8t6btvlgVZU4s=; b=Q9x8Mhe3xzlw2Sd4b9rS6ra87WliAnCqV/MSd/wh+7/Gqk1nHCFwKRgKJbht2MpbH+ ILMtWdVQbdrLvIam9qP9c7f+/4J1+B8C0qBNlybe3U4uZu7G30LovZx5eTklQAea3qdf q3NSXM8xb/iE+wrWEm1buFCc1LIL63ndr0CzuBrNVEvTWm5ikDjO6YZPN0rB62N9iUQl qfl9OCbvlNlMKI+rNjRCE1Q5IcS+tANhfFxvnhqkMQ2MkUCeace/gHjBFRDwnSx1Uv6y I2a97pj8iXSEvvYFyBFjl+KBnLGNONikCh1NVVWo1sYaqKJkwzbhIW0Y4igRjgT01Wj4 dUzA== X-Gm-Message-State: AOPr4FWe14P6QfDYcS+iQ3mEwN8uAwxygLp57ZeyNEHR501z+LcPtqkEq/3SaNzS/sMtYQ== X-Received: by 10.194.5.101 with SMTP id r5mr32614133wjr.47.1460898730457; Sun, 17 Apr 2016 06:12:10 -0700 (PDT) Original-Received: from [192.168.1.2] ([185.105.175.24]) by smtp.googlemail.com with ESMTPSA id q127sm21458149wmd.13.2016.04.17.06.12.08 (version=TLSv1/SSLv3 cipher=OTHER); Sun, 17 Apr 2016 06:12:09 -0700 (PDT) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.0 In-Reply-To: <87y48cctr6.fsf@gmx.de> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2a00:1450:400c:c09::244 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:203011 Archived-At: On 04/17/2016 03:19 PM, Michael Albinus wrote: > Dmitry Gutov writes: > >> I'm not arguing in favor of leaving mistakes in the manual. But I >> think it should be strictly a derivative work. I.e. the docstrings >> must contain the complete information (if maybe presented in a terse >> fashion), and the manual could rephrase that, only to make it more >> accessible (but not more informative). > > I still don't understand what problem you discuss. There are docstrings, > and there are manuals. Both have their reasons to exist. My problem is that you stated the lack of a manual as the reason for your lack of understanding of VC's internals. I'm saying the problem is them being documented insufficiently in the code. And, like I mentioned, if you go ahead and write the newfound revelations in the manual, but not anywhere else, a certain slice of developers is going to miss out. To expand on my message in http://debbugs.gnu.org/cgi/bugreport.cgi?bug=20637#91, an example: If we make a decision that vc-BACKEND-state can rely on FILE not having state `unregistered' (I'm not saying we should; it's just one option), that information should go into the Commentary at the top of vc.el (probably into the description of the `state' command), but... > I believe it would be good if vc-* functions are covered in a > manual. What is the problem with this? ...if it also finds its way into a manual later, I don't see any harm. To put a different spin on my statement earlier: if neither the docstrings, nor the manual are considered the Single Source of Truth, to read a reasonably complete description of a function, I'd have to read both the docstring and the manual. And that's just wasteful. And even the personal preferences aside, we can't make the manual to be the SSOT because most functions are not documented there.