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: Trunk still not open Date: Sun, 16 Mar 2014 02:26:21 +0200 Message-ID: <5324EFAD.3090206@yandex.ru> References: <6xwqfxhl88.fsf@fencepost.gnu.org> <83txb1mcsy.fsf@gnu.org> <87siqlku0i.fsf@uwakimon.sk.tsukuba.ac.jp> <87wqfxari2.fsf@yandex.ru> <87r464luge.fsf@uwakimon.sk.tsukuba.ac.jp> <532318E6.6030706@yandex.ru> <838uscdcj6.fsf@gnu.org> <5323F1AF.1040902@yandex.ru> <8338ijdebh.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1394929608 11784 80.91.229.3 (16 Mar 2014 00:26:48 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 16 Mar 2014 00:26:48 +0000 (UTC) Cc: stephen@xemacs.org, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Mar 16 01:26:56 2014 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 1WOyum-0001En-CF for ged-emacs-devel@m.gmane.org; Sun, 16 Mar 2014 01:26:56 +0100 Original-Received: from localhost ([::1]:51558 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WOyul-0004UB-Sy for ged-emacs-devel@m.gmane.org; Sat, 15 Mar 2014 20:26:55 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39341) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WOyua-0004Fj-Ox for emacs-devel@gnu.org; Sat, 15 Mar 2014 20:26:53 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WOyuS-0008UU-Cn for emacs-devel@gnu.org; Sat, 15 Mar 2014 20:26:44 -0400 Original-Received: from mail-ee0-x235.google.com ([2a00:1450:4013:c00::235]:50085) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WOyuJ-0008Rd-5x; Sat, 15 Mar 2014 20:26:27 -0400 Original-Received: by mail-ee0-f53.google.com with SMTP id b57so2112176eek.12 for ; Sat, 15 Mar 2014 17:26:26 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=sender:message-id:date:from:user-agent:mime-version:to:cc:subject :references:in-reply-to:content-type:content-transfer-encoding; bh=ijV1xu/EQRxkZjrcnszqiAnGXhfHJsbV8irhYIier6k=; b=krhEFC8x6MJ8JJwVta7KMeEWBpRJbh7OPW7bFCRv83zWV8vq3dseZg+KCBNC6xRRXa 72Uv8DHceykejW2RREjDBvBoks6Qk9wH0T7eIuJZiyFShxmYeyuKZXPGcMgzQ+6G192G 2GQIRuuHQX46br/Xv44U3lEtq14WjdzcpR4xz4NYE2arYvFTBUosIerg4BSZMUHcaQWF Phq2DohSve3xcbbECN5AI7UpfVzSXMImoInqtO79TgwdWBeOF6J4apb0k/Y6vUwqR4og 00n/lg2BVsLC/nVhslGo/yovxYyzp0eHBlu9mdWYld7ns31cM/KEjAbm7bOl0xGSAFyz ZONw== X-Received: by 10.14.241.139 with SMTP id g11mr8582058eer.49.1394929585956; Sat, 15 Mar 2014 17:26:25 -0700 (PDT) Original-Received: from [192.168.10.2] (62-27-225.netrun.cytanet.com.cy. [62.228.27.225]) by mx.google.com with ESMTPSA id s46sm28286271ees.3.2014.03.15.17.26.24 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Sat, 15 Mar 2014 17:26:25 -0700 (PDT) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:24.0) Gecko/20100101 Thunderbird/24.3.0 In-Reply-To: <8338ijdebh.fsf@gnu.org> X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2a00:1450:4013:c00::235 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:170400 Archived-At: On 15.03.2014 11:02, Eli Zaretskii wrote: > Therefore, you need to know what was expected of the code which you > modified. This is exacerbated in Emacs by the lack of good coverage > by existing tests, so in many cases you will be writing a test for > modified implementation without having a test for the existing > implementation. In those cases, your _only_ source to learn what the > existing implementation tried to do will be the docs. IME either the docstrings are sufficient, or you have to dig into the code anyway, see the implementation, and often use `vc-annotate', for older code, to find out why things were done one way or another at some point of time. Bug references also help. Manuals usually don't contain historical data, or references to bugs. > It's not always possible to get familiar with the code enough to > understand how it was supposed to work and what effects it was > supposed to produce, without investing unduly large or even > impractical effort. Many times, you fix a bug or add a feature whose > effects are localized enough to make it unnecessary to study too much > surrounding or supporting code. Then just skimmings the surrounding code or its docstrings might be enough. > Sometimes, the code you modify use > some infrastructure which you understand only vaguely, but writing a > test for your changes requires to know some specific detail about > those other parts. If it's not in the docstrings, I'll probably have to read the code anyway. > As another data point, consider the bug reports which say "the docs > says FOO should work such-and-such, but in fact I see a different > behavior". IOW, people use the docs as a kind of contract, and > rightfully so. Documenting the behavior goes a long way towards > explaining users what they should expect. This can be applied to docstrings just as well. >> Lisp packages often put the intro or overview in the Commentary, though. > > Yes, but it's rare to have there enough stuff to cover the ground. > And if that overview is good enough, copying it into the manual and > adding the necessary markup is almost trivial. And then you'll have to maintain the text in both places.