On Fri, Apr 26, 2024 at 11:21 AM Luis Felipe <sirgazil@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á...
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)
OpenPGP_0x0AB0D067012F08C3.asc