From mboxrd@z Thu Jan 1 00:00:00 1970 From: =?UTF-8?Q?G=C3=A1bor_Boskovits?= Subject: Re: Missing code comments in guix source: 2 examples from gnu/services Date: Mon, 5 Nov 2018 09:40:04 +0100 Message-ID: References: <427b45c9-f2c6-1394-c5e6-aecf3e30570b@riseup.net> 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]:50863) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gJace-0004rP-W6 for guix-devel@gnu.org; Mon, 05 Nov 2018 03:52:37 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gJaQl-0004WP-Bn for guix-devel@gnu.org; Mon, 05 Nov 2018 03:40:20 -0500 Received: from mail-it1-x12b.google.com ([2607:f8b0:4864:20::12b]:34108) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gJaQk-0004GB-7D for guix-devel@gnu.org; Mon, 05 Nov 2018 03:40:18 -0500 Received: by mail-it1-x12b.google.com with SMTP id t189-v6so7134570itf.1 for ; Mon, 05 Nov 2018 00:40:16 -0800 (PST) In-Reply-To: <427b45c9-f2c6-1394-c5e6-aecf3e30570b@riseup.net> 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" To: swedebugia@riseup.net Cc: Guix-devel Hello, swedebugia ezt =C3=ADrta (id=C5=91pont: 2018. nov. = 5., H, 9:33): > > Hi > > Reading this http://git.savannah.gnu.org/cgit/guix.git/tree/gnu/services/= monitoring.scm > > I would like to know what darkstat is without having to look elsewhere. > > None of the (define-s have docstrings and the top comment > > ;;; > ;;; darkstat > ;;; > > does not help much. > > prometheus-node-exporter-shepherd-service is just as little documented in= the same file. From the file I have no idea what this does as its only doc= umentation is: > > (shepherd-service > (documentation "Prometheus node exporter.") > > --- > Thanks for pointing this out, I will fix this in prometheus-node-exporter. Can you point me to a service where the documentation is statisfactory? > http://git.savannah.gnu.org/cgit/guix.git/tree/gnu/services/admin.scm > > Is generally a little better documented with docstrings. But here a heade= r like > > ;;; > ;;; darkstat > ;;; > > is missing for rottlog and also a short description of what rottlog does.= (from the name and peeking at the code I'm guessing it rotates logs but ma= ny services have arbitrary names, especially to newcomers on GNU/Linux) > > -- > Cheers > Swedebugia Best regards, g_bor