[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Some issues with guile

From: Luis Felipe
Subject: Re: Some issues with guile
Date: Sat, 27 Apr 2024 20:32:50 +0000
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.15.0

El 27/04/24 a las 7:28, Nikolaos Chatzikonstantinou escribió:
On Fri, Apr 26, 2024 at 11:21 AM Luis Felipe <> wrote:
Hi Nikolaos,
Hello Luis!

El 26/04/24 a las 7:05, Nikolaos Chatzikonstantinou escribió:
2. Documentation extraction sucks.
    - documentá in its page does not include an example of how it works!
      Not a line of code to explain to the user which documentation is
      extracted. I could not understand how to use it.
Yeah, I didn't want to include how to document code in Documentá.
Instead, I wanted to propose adding that documentation to Guile's
documentation and link to it from Documentá. But I haven't made the time
to write the proposed section.
Just add /something/ with a visible TODO that your wish is to have
guile document it instead. It should be prominent too, not buried 10
layers deep. You could just say "read the source code of documentá for
examples." When I looked at your documentation, I spent about 10
minutes trying to figure this out, and I was frustrated when I
couldn't find any examples. The user is left thinking they're an idiot
(they very well may be!) for not RTFM well enough and frustrated,
unlikely to look back at documentá...

I'll see what I can do to make it easier :)

Currently, Documentá can extract module documentation and procedure
documentation. It also documents variables, record types, and macros
exported by modules, but it simply lists them (record type fields are
listed too), it doesn't extract any particular documentation added by
human code writers. I haven't found, and in some cases investigated, a
way to properly document variables, macros, record types and GOOPS
clases using human-written documentation strings. But I want to have
that too.
What is the issue with this?

     ;;; my favorite constant
     (define magic 42)

That I don't know any existing mechanism to tell that the comment is the documentation of the variable. I'd prefer something like Elisp (

  defvar symbol [value [doc-string]]

  (defvar bar 23
    "The normal weight of a bar.")

Attachment: OpenPGP_0x0AB0D067012F08C3.asc
Description: OpenPGP public key

Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]