From mboxrd@z Thu Jan 1 00:00:00 1970 From: swedebugia Subject: Missing code comments in guix source: 2 examples from gnu/services Date: Mon, 5 Nov 2018 09:30:14 +0100 Message-ID: <427b45c9-f2c6-1394-c5e6-aecf3e30570b@riseup.net> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="------------2E3FB646D105E78DE2BB4406" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:44720) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gJaHC-0000UC-V5 for guix-devel@gnu.org; Mon, 05 Nov 2018 03:30:29 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gJaH7-0006JB-EX for guix-devel@gnu.org; Mon, 05 Nov 2018 03:30:26 -0500 Received: from mx1.riseup.net ([198.252.153.129]:42637) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1gJaH6-00067x-P1 for guix-devel@gnu.org; Mon, 05 Nov 2018 03:30:21 -0500 Received: from cotinga.riseup.net (cotinga-pn.riseup.net [10.0.1.164]) (using TLSv1 with cipher ECDHE-RSA-AES256-SHA (256/256 bits)) (Client CN "*.riseup.net", Issuer "COMODO RSA Domain Validation Secure Server CA" (verified OK)) by mx1.riseup.net (Postfix) with ESMTPS id 7373B1A0213 for ; Mon, 5 Nov 2018 00:30:19 -0800 (PST) Received: from [127.0.0.1] (localhost [127.0.0.1]) by cotinga.riseup.net with ESMTPSA id B99DDE6F9F for ; Mon, 5 Nov 2018 00:30:18 -0800 (PST) Content-Language: en-US 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: guix-devel@gnu.org This is a multi-part message in MIME format. --------------2E3FB646D105E78DE2BB4406 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit 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 documentation is: |(shepherd-service (documentation "Prometheus node exporter.")| --- http://git.savannah.gnu.org/cgit/guix.git/tree/gnu/services/admin.scm Is generally a little better documented with docstrings. But here a header 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 many services have arbitrary names, especially to newcomers on GNU/Linux) -- Cheers Swedebugia --------------2E3FB646D105E78DE2BB4406 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: 7bit

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 documentation is:

     (shepherd-service
      (documentation "Prometheus node exporter.")

---

http://git.savannah.gnu.org/cgit/guix.git/tree/gnu/services/admin.scm

Is generally a little better documented with docstrings. But here a header 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 many services have arbitrary names, especially to newcomers on GNU/Linux)

-- 
Cheers
Swedebugia
--------------2E3FB646D105E78DE2BB4406-- 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 From mboxrd@z Thu Jan 1 00:00:00 1970 From: swedebugia Subject: Re: Missing code comments in guix source: 2 examples from gnu/services Date: Mon, 5 Nov 2018 10:14:14 +0100 Message-ID: <3cb4b880-668a-5501-8f22-58d7c452c1a5@riseup.net> References: <427b45c9-f2c6-1394-c5e6-aecf3e30570b@riseup.net> Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="------------1D037D36BE49AE5FEAEDA310" Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:60650) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gJaxx-0003TL-8C for guix-devel@gnu.org; Mon, 05 Nov 2018 04:14:40 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gJaxj-0004SH-5i for guix-devel@gnu.org; Mon, 05 Nov 2018 04:14:28 -0500 Received: from mx1.riseup.net ([198.252.153.129]:49855) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1gJaxi-0003Ku-H6 for guix-devel@gnu.org; Mon, 05 Nov 2018 04:14:22 -0500 In-Reply-To: Content-Language: en-US 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: =?UTF-8?Q?G=c3=a1bor_Boskovits?= , guix-devel@gnu.org This is a multi-part message in MIME format. --------------1D037D36BE49AE5FEAEDA310 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: quoted-printable Hi Thanks for the quick reply :) On 2018-11-05 09:40, G=C3=A1bor Boskovits wrote: > Hello, > > swedebugia ezt =C3=ADrta (id=C5=91p= ont: 2018. nov.=20 5., > H, 9:33): >> >> >> prometheus-node-exporter-shepherd-service is=20 just as little >> documented in the same file. From the file I have no=20 idea what this >> does as its only documentation is: >> >>=20 (shepherd-service (documentation "Prometheus node exporter.") >> >> ---=20 >> > > Thanks for pointing this out, I will fix this in >=20 prometheus-node-exporter. Thank you :) > > Can you point me to a service where the documentation is >=20 statisfactory? Actually I cannot yet as I have only read these two files. I will get=20 back to you on that one. I'm going to install geiser to try the autodoc function, but if I=20 understood correctly this only works with docstrings, NOT say package=20 records. Do we have a tool in emacs/geiser for looking up a package synopsis=20 based on the package-name at point? Anyway when printing on paper and reading via a git client/git web this=20 won't help. --=20 Cheers Swedebugia --------------1D037D36BE49AE5FEAEDA310 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: quoted-printable

Hi

Thanks for the quick reply :)


On 2018-11-05 09:40, G=C3=A1bor Boskovits wrote:
&= gt; Hello, >=20 > swedebugia <swedebugia@riseup.net> ezt =C3=ADrta (id=C5=91= pont: 2018. nov. 5., > H, 9:33): >>=20 >>=20 >> prometheus-node-exporter-shepherd-service is just as little >> documented in the same file. From the file I have no idea what t= his >> does as its only documentation is: >>=20 >> (shepherd-service (documentation "Prometheus node exporter.") >>=20 >> --- >>=20 >=20 > Thanks for pointing this out, I will fix this in > prometheus-node-exporter. Thank you :)
&= gt;=20 > Can you point me to a service where the documentation is > statisfactory?

Actually I cannot yet as I have only read these two files. I will get back to you on that one.

I'm going to install geiser to try the autodoc function, but if I understood correctly this only works with docstrings, NOT say package records.

Do we have a tool in emacs/geiser for looking up a package synopsis based on the package-name at point?

Anyway when printing on paper and reading via a git client/git web this won't help.

--
Cheers
Swedebugia

--------------1D037D36BE49AE5FEAEDA310-- 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 11:39:15 +0100 Message-ID: References: <427b45c9-f2c6-1394-c5e6-aecf3e30570b@riseup.net> <3cb4b880-668a-5501-8f22-58d7c452c1a5@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]:59990) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gJcIN-00074z-82 for guix-devel@gnu.org; Mon, 05 Nov 2018 05:39:48 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gJcIM-0003Cj-5m for guix-devel@gnu.org; Mon, 05 Nov 2018 05:39:47 -0500 Received: from mail-io1-xd31.google.com ([2607:f8b0:4864:20::d31]:37146) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gJcIL-0007G1-Sa for guix-devel@gnu.org; Mon, 05 Nov 2018 05:39:46 -0500 Received: by mail-io1-xd31.google.com with SMTP id k17-v6so6113458ioc.4 for ; Mon, 05 Nov 2018 02:39:27 -0800 (PST) In-Reply-To: <3cb4b880-668a-5501-8f22-58d7c452c1a5@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, 10:14): > > Hi > > Thanks for the quick reply :) > > > On 2018-11-05 09:40, G=C3=A1bor Boskovits wrote: > > Hello, > > swedebugia ezt =C3=ADrta (id=C5=91po= nt: 2018. nov. 5., > H, 9:33): >> >> >> prometheus-node-exporter-shepherd-s= ervice is just as little >> documented in the same file. From the file I ha= ve no idea what this >> does as its only documentation is: >> >> (shepherd-= service (documentation "Prometheus node exporter.") >> >> --- >> > > Thanks= for pointing this out, I will fix this in > prometheus-node-exporter. Than= k you :) > > > Can you point me to a service where the documentation is > statisfact= ory? > > Actually I cannot yet as I have only read these two files. I will get bac= k to you on that one. > > I'm going to install geiser to try the autodoc function, but if I underst= ood correctly this only works with docstrings, NOT say package records. > > Do we have a tool in emacs/geiser for looking up a package synopsis based= on the package-name at point? > I guess there is something like this in emacs-guix, but I do not use that extensively. > Anyway when printing on paper and reading via a git client/git web this w= on't help. > > -- > Cheers > Swedebugia > Best regards, g_bor From mboxrd@z Thu Jan 1 00:00:00 1970 From: ludo@gnu.org (Ludovic =?utf-8?Q?Court=C3=A8s?=) Subject: Re: Missing code comments in guix source: 2 examples from gnu/services Date: Tue, 06 Nov 2018 15:15:09 +0100 Message-ID: <87k1lq1edu.fsf@gnu.org> 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]:46629) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gK28e-0001lp-K9 for guix-devel@gnu.org; Tue, 06 Nov 2018 09:15:34 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gK28M-0001fL-SD for guix-devel@gnu.org; Tue, 06 Nov 2018 09:15:15 -0500 In-Reply-To: (=?utf-8?Q?=22G=C3=A1bor?= Boskovits"'s message of "Mon, 5 Nov 2018 09:40:04 +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" To: =?utf-8?Q?G=C3=A1bor?= Boskovits Cc: Guix-devel Hi, G=C3=A1bor Boskovits skribis: > swedebugia ezt =C3=ADrta (id=C5=91pont: 2018. nov= . 5., H, 9:33): [...] >> prometheus-node-exporter-shepherd-service is just as little documented i= n the same file. From the file I have no idea what this does as its only do= cumentation 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? Note that the =E2=80=98documentation=E2=80=99 field that you see above is w= hat =E2=80=9Cherd doc prometheus-node-exporter=E2=80=9D shows. It should be terse compared to the =E2=80=98documentation=E2=80=99 field of =E2=80=98service-type=E2=80=99. Thanks, Ludo=E2=80=99. From mboxrd@z Thu Jan 1 00:00:00 1970 From: swedebugia Subject: Re: Missing code comments in guix source: 2 examples from gnu/services Date: Fri, 9 Nov 2018 00:12:17 +0100 Message-ID: <7021b5f9-107a-f5e3-11af-13c75877da1a@riseup.net> References: <427b45c9-f2c6-1394-c5e6-aecf3e30570b@riseup.net> <87k1lq1edu.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:56645) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gL0TQ-0004EX-8c for guix-devel@gnu.org; Fri, 09 Nov 2018 01:40:56 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gL0TI-0003HR-Qv for guix-devel@gnu.org; Fri, 09 Nov 2018 01:40:53 -0500 In-Reply-To: <87k1lq1edu.fsf@gnu.org> Content-Language: sv-FI 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: =?UTF-8?Q?Ludovic_Court=c3=a8s?= , =?UTF-8?Q?G=c3=a1bor_Boskovits?= Cc: Guix-devel On 2018-11-06 15:15, Ludovic Court=C3=A8s wrote: > Hi, > > G=C3=A1bor Boskovits skribis: > >> swedebugia ezt =C3=ADrta (id=C5=91pont: 2018. = nov. 5., H, 9:33): > [...] > >>> prometheus-node-exporter-shepherd-service is just as little documente= d in the same file. From the file I have no idea what this does as its on= ly documentation is: >>> >>> (shepherd-service >>> (documentation "Prometheus node exporter.") >>> >>> --- >>> >> Thanks for pointing this out, I will fix this in prometheus-node-expor= ter. >> Can you point me to a service where the documentation is statisfactory= ? > Note that the =E2=80=98documentation=E2=80=99 field that you see above = is what =E2=80=9Cherd doc > prometheus-node-exporter=E2=80=9D shows. It should be terse compared t= o the > =E2=80=98documentation=E2=80=99 field of =E2=80=98service-type=E2=80=99= . Ok, thanks. --=20 Cheers Swedebugia