From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mathieu Lirzin Subject: Re: 01/01: doc: Typos and small stylistic changes. Date: Sun, 06 Mar 2016 20:13:21 +0100 Message-ID: <87a8mbctda.fsf@gnu.org> References: <20160305152745.10002.35086@vcs.savannah.gnu.org> <877fhg38b2.fsf@gnu.org> <20160306131042.GA13567@solar> <87fuw3d8ip.fsf@gnu.org> <20160306152646.GA16301@solar> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:55805) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ace7R-0000SS-Tr for guix-devel@gnu.org; Sun, 06 Mar 2016 14:13:35 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ace7Q-0000Nl-VD for guix-devel@gnu.org; Sun, 06 Mar 2016 14:13:33 -0500 In-Reply-To: <20160306152646.GA16301@solar> (Andreas Enge's message of "Sun, 6 Mar 2016 16:26:46 +0100") List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org To: Andreas Enge Cc: guix-devel@gnu.org Andreas Enge writes: > On Sun, Mar 06, 2016 at 02:46:06PM +0100, Mathieu Lirzin wrote: >> It is painful but necessary: >> https://www.gnu.org/prep/standards/html_node/Doc-Strings-and-Manuals.h= tml#Doc-Strings-and-Manuals >> A way to understand why this is important is to read some of the >> "documentation" used by the Java APIs. > I agree. However, here we _do_ copy verbatim docstrings from the source c= ode > into the manual, which is also fine. And then we are expected to back-port > changes to the supposedly manually written manual :-) back to the docstr= ings. > So it would be nice if there were a system to just include selected > docstrings; a texinfo command @docstring{guix-service-type} or something = like > that. But I think it does not exist. OK. Then my "generic" response would be that this is a symptom of a problem in the manual or the docstring or both. The only desirable automations I see for documentation, are a thing that checks that procedure signatures from the manual are matching the actual implementation, and a way for your editor to retrieve the doc strings (more conveniently than grep), in order to manually check if something should be updated in both. If another problem is lack of time for writing documentation. I think the correct fix is to replace the copy/pasted doc-strings with something like: --8<---------------cut here---------------start------------->8--- FIXME: Document this part. Please refer to source file =E2=80=98$foo/bar.scm=E2=80=99 for details. --8<---------------cut here---------------end--------------->8--- :) --=20 Mathieu Lirzin