El 27/04/24 a las 7:28, Nikolaos Chatzikonstantinou escribió:
On Fri, Apr 26, 2024 at 11:21 AM Luis Felipe <sirga...@zoho.com> 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 (https://www.gnu.org/software/emacs/manual/html_node/elisp/Defining-Variables.html):
defvar symbol [value [doc-string]] (defvar bar 23 "The normal weight of a bar.")
OpenPGP_0x0AB0D067012F08C3.asc
Description: OpenPGP public key
OpenPGP_signature
Description: OpenPGP digital signature