From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:50160) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1eO2cL-00052R-0F for guix-patches@gnu.org; Sun, 10 Dec 2017 09:30:10 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1eO2cG-0001MV-2l for guix-patches@gnu.org; Sun, 10 Dec 2017 09:30:09 -0500 Received: from debbugs.gnu.org ([208.118.235.43]:45954) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1eO2cF-0001M2-V2 for guix-patches@gnu.org; Sun, 10 Dec 2017 09:30:04 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1eO2cE-0005Wy-5i for guix-patches@gnu.org; Sun, 10 Dec 2017 09:30:03 -0500 Subject: [bug#29438] Generating service documentation Resent-Message-ID: From: ludo@gnu.org (Ludovic =?UTF-8?Q?Court=C3=A8s?=) References: <20171125150531.26769-1-clement@lassieur.org> <87d145vw5z.fsf@gnu.org> <87shciogs0.fsf@lassieur.org> Date: Sun, 10 Dec 2017 15:29:08 +0100 In-Reply-To: <87shciogs0.fsf@lassieur.org> ("=?UTF-8?Q?Cl=C3=A9ment?= Lassieur"'s message of "Sun, 10 Dec 2017 14:26:39 +0100") Message-ID: <87zi6qbqrv.fsf_-_@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+kyle=kyleam.com@gnu.org Sender: "Guix-patches" To: =?UTF-8?Q?Cl=C3=A9ment?= Lassieur Cc: 29438@debbugs.gnu.org Hi Cl=C3=A9ment, Cl=C3=A9ment Lassieur skribis: > It's a bit sad that most services' docstrings are not in sync with the > .texi file, it would be great to have an automated mechanism to update > the documentation. I use a hackish Emacs snippet to maintain Prosody > documentation, but something like "make generate-documentation > " would be much better. I'll think about it. > > @c The following documentation was initially generated by > @c (generate-documentation) in (gnu services messaging). Manually mainta= ined > @c documentation is better, so we shouldn't hesitate to edit below as > @c needed. However if the change you want to make to this documentation > @c can be done in an automated way, it's probably easier to change > @c (generate-documentation) than to make it below and have to deal with > @c the churn as Prosody updates. > > I don't really agree with this comment that can be found in several > places in our documentation. I believe that when there is a > (generate-documentation) procedure, manual edits shouldn't be > encouraged. But it's probably not worth updating it while there is no > easy way to automatically generate the documentation. It=E2=80=99s complicated. Automatically-generated documentation can be use= ful as a reference, but it doesn=E2=80=99t really help you get started. It=E2= =80=99s typically a very unfriendly, Javadoc-style, dump of functions/fields. It think that=E2=80=99s what this comment is about: generated doc is a star= t, but it=E2=80=99s not doing much of a service to our users. Now, if the choice is between terse-and-outdated doc and terse-but-automatically-updated doc, the latter is preferable. It=E2=80=99s just not ideal IMO. >> Also, I was thinking that =E2=80=98guix system search=E2=80=99 could dis= play >> field/default-value pairs. I=E2=80=99m not 100% sure it=E2=80=99s a goo= d idea because >> that could be very verbose. >> >> Thoughts? > > It would be verbose indeed, and if people want to have details about > fields and default values, they can search the manual. Yeah. I was thinking that it might be helpful, let=E2=80=99s say if you=E2= =80=99re using openssh-service-type and you don=E2=80=99t remember the exact name of= an option having to do with authentication. Dunno. Thanks, Ludo=E2=80=99.