unofficial mirror of guix-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Missing code comments in guix source: 2 examples from gnu/services
@ 2018-11-05  8:30 swedebugia
  2018-11-05  8:40 ` Gábor Boskovits
  0 siblings, 1 reply; 6+ messages in thread
From: swedebugia @ 2018-11-05  8:30 UTC (permalink / raw)
  To: guix-devel

[-- Attachment #1: Type: text/plain, Size: 927 bytes --]

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


[-- Attachment #2: Type: text/html, Size: 2048 bytes --]

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: Missing code comments in guix source: 2 examples from gnu/services
  2018-11-05  8:30 Missing code comments in guix source: 2 examples from gnu/services swedebugia
@ 2018-11-05  8:40 ` Gábor Boskovits
  2018-11-05  9:14   ` swedebugia
  2018-11-06 14:15   ` Ludovic Courtès
  0 siblings, 2 replies; 6+ messages in thread
From: Gábor Boskovits @ 2018-11-05  8:40 UTC (permalink / raw)
  To: swedebugia; +Cc: Guix-devel

Hello,

swedebugia <swedebugia@riseup.net> ezt írta (időpont: 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 documentation 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 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

Best regards,
g_bor

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: Missing code comments in guix source: 2 examples from gnu/services
  2018-11-05  8:40 ` Gábor Boskovits
@ 2018-11-05  9:14   ` swedebugia
  2018-11-05 10:39     ` Gábor Boskovits
  2018-11-06 14:15   ` Ludovic Courtès
  1 sibling, 1 reply; 6+ messages in thread
From: swedebugia @ 2018-11-05  9:14 UTC (permalink / raw)
  To: Gábor Boskovits, guix-devel

[-- Attachment #1: Type: text/plain, Size: 1112 bytes --]

Hi

Thanks for the quick reply :)


On 2018-11-05 09:40, Gábor Boskovits wrote:
> Hello,  > > swedebugia <swedebugia@riseup.net> ezt írta (időpont: 2018. nov. 
5., > H, 9:33): >> >> >> 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.") >> >> --- 
 >> > > Thanks for pointing this out, I will fix this in > 
prometheus-node-exporter. Thank you :)
>  > 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


[-- Attachment #2: Type: text/html, Size: 1773 bytes --]

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: Missing code comments in guix source: 2 examples from gnu/services
  2018-11-05  9:14   ` swedebugia
@ 2018-11-05 10:39     ` Gábor Boskovits
  0 siblings, 0 replies; 6+ messages in thread
From: Gábor Boskovits @ 2018-11-05 10:39 UTC (permalink / raw)
  To: swedebugia; +Cc: Guix-devel

Hello,

swedebugia <swedebugia@riseup.net> ezt írta (időpont: 2018. nov. 5., H, 10:14):
>
> Hi
>
> Thanks for the quick reply :)
>
>
> On 2018-11-05 09:40, Gábor Boskovits wrote:
> > Hello, > > swedebugia <swedebugia@riseup.net> ezt írta (időpont: 2018. nov. 5., > H, 9:33): >> >> >> 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.") >> >> --- >> > > Thanks for pointing this out, I will fix this in > prometheus-node-exporter. Thank you :)
> > > 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?
>

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 won't help.
>
> --
> Cheers
> Swedebugia
>

Best regards,
g_bor

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: Missing code comments in guix source: 2 examples from gnu/services
  2018-11-05  8:40 ` Gábor Boskovits
  2018-11-05  9:14   ` swedebugia
@ 2018-11-06 14:15   ` Ludovic Courtès
  2018-11-08 23:12     ` swedebugia
  1 sibling, 1 reply; 6+ messages in thread
From: Ludovic Courtès @ 2018-11-06 14:15 UTC (permalink / raw)
  To: Gábor Boskovits; +Cc: Guix-devel

Hi,

Gábor Boskovits <boskovits@gmail.com> skribis:

> swedebugia <swedebugia@riseup.net> ezt írta (időpont: 2018. nov. 5., H, 9:33):

[...]

>> 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.")
>>
>> ---
>>
>
> 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 ‘documentation’ field that you see above is what “herd doc
prometheus-node-exporter” shows.  It should be terse compared to the
‘documentation’ field of ‘service-type’.

Thanks,
Ludo’.

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: Missing code comments in guix source: 2 examples from gnu/services
  2018-11-06 14:15   ` Ludovic Courtès
@ 2018-11-08 23:12     ` swedebugia
  0 siblings, 0 replies; 6+ messages in thread
From: swedebugia @ 2018-11-08 23:12 UTC (permalink / raw)
  To: Ludovic Courtès, Gábor Boskovits; +Cc: Guix-devel

On 2018-11-06 15:15, Ludovic Courtès wrote:
> Hi,
>
> Gábor Boskovits <boskovits@gmail.com> skribis:
>
>> swedebugia <swedebugia@riseup.net> ezt írta (időpont: 2018. nov. 5., H, 9:33):
> [...]
>
>>> 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.")
>>>
>>> ---
>>>
>> 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 ‘documentation’ field that you see above is what “herd doc
> prometheus-node-exporter” shows.  It should be terse compared to the
> ‘documentation’ field of ‘service-type’.
Ok, thanks.

-- 
Cheers Swedebugia

^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2018-11-09  6:40 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2018-11-05  8:30 Missing code comments in guix source: 2 examples from gnu/services swedebugia
2018-11-05  8:40 ` Gábor Boskovits
2018-11-05  9:14   ` swedebugia
2018-11-05 10:39     ` Gábor Boskovits
2018-11-06 14:15   ` Ludovic Courtès
2018-11-08 23:12     ` swedebugia

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/guix.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).