[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: |
Fri, 26 Apr 2024 15:21:04 +0000 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.15.0 |
Hi Nikolaos,
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.
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.
You can see examples of module and procedure documentation in
Documentá's source
(https://codeberg.org/luis-felipe/guile-documenta/src/branch/trunk/documenta).
Note that for module documentation Documentá supports the conventional
format
;;; Commentary:
;;; Your module documentation here ↓
;;; Code:
;;; Your code here ↓
Guile Scheme comments in the "Commentary" section are considered module
documentation. You can use block comments too, the ones surrounded in #|
... |#, instead of multiple line comments (see Documentá source code for
examples).
Finally, better structuring, indexing and linking of generated API
documentation are planned. I also want to explore exporting to Org format.
Hope that helps,
OpenPGP_0x0AB0D067012F08C3.asc
Description: OpenPGP public key
OpenPGP_signature
Description: OpenPGP digital signature