From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Next release from master Date: Wed, 10 Feb 2016 20:03:47 +0200 Message-ID: <83y4asa1do.fsf@gnu.org> References: <8qegda3kfg.fsf@fencepost.gnu.org> <83h9i695n5.fsf@gnu.org> <87si118q6e.fsf@gnus.org> <877fid5u3e.fsf@gmx.us> <87bn7pwgaj.fsf@wanadoo.es> <87y4atqq25.fsf@gnus.org> <877fidwaka.fsf@wanadoo.es> <8737t1ckh9.fsf@gmail.com> <56BAAF79.2010109@yandex.ru> <87pow5us9i.fsf@wanadoo.es> <56BAB8F0.1060501@yandex.ru> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1455127464 24373 80.91.229.3 (10 Feb 2016 18:04:24 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 10 Feb 2016 18:04:24 +0000 (UTC) Cc: ofv@wanadoo.es, emacs-devel@gnu.org To: Dmitry Gutov Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Feb 10 19:04: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 1aTZ7i-0000RP-Cs for ged-emacs-devel@m.gmane.org; Wed, 10 Feb 2016 19:04:18 +0100 Original-Received: from localhost ([::1]:41617 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aTZ7h-0004WB-Lb for ged-emacs-devel@m.gmane.org; Wed, 10 Feb 2016 13:04:17 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53109) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aTZ7T-0004W3-A6 for emacs-devel@gnu.org; Wed, 10 Feb 2016 13:04:04 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aTZ7P-0002mP-CR for emacs-devel@gnu.org; Wed, 10 Feb 2016 13:04:03 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:40390) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aTZ7P-0002mL-8t; Wed, 10 Feb 2016 13:03:59 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:2814 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aTZ7N-0002ax-MO; Wed, 10 Feb 2016 13:03:58 -0500 In-reply-to: <56BAB8F0.1060501@yandex.ru> (message from Dmitry Gutov on Wed, 10 Feb 2016 06:13:36 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e 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:199705 Archived-At: > From: Dmitry Gutov > Date: Wed, 10 Feb 2016 06:13:36 +0200 > > IMO it is very reasonable to require documenting the contributed > changes. Without that, code reviews and testing are much harder. > > Not if the feature has appropriate docstrings and header commentary. IME, people who write high-quality doc strings usually also document the changes in the manual. So, sadly, going by the doc strings and the commentary still requires a non-trivial amount of work for many changes. > Hopefully, one doesn't have to read the code to translate the docstrings into the manual (AFAICT, Eli tried not to). This can only be done with user-level documentation, not with stuff in ELisp manual. In the latter case, it normally doesn't work. Especially if the subject matter is something one has little knowledge about. E.g., when I worked on cl-generic.el, even reading the code didn't help enough, because I was not familiar with CLOS before. > The person who does the documentation also can ask questions. Yes, but that makes the process much less efficient, even if the person who wrote the code lives in a close time zone. A job that could take several minutes will take hours or days if one must ask questions to figure things out. That's what happened with 'pcase', for example.