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
