[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: 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 ( 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: 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]