Re: Some issues with guile

[Luis Felipe <sirgazil@zoho.com>]

[-- Attachment #1.1.1: Type: text/plain, Size: 1863 bytes --]

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,

[-- Attachment #1.1.2: OpenPGP public key --]
[-- Type: application/pgp-keys, Size: 2881 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 495 bytes --]