Re: Some issues with guile

[Nikolaos Chatzikonstantinou <nchatz314@gmail.com>]

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)

Regards,
Nikolaos Chatzikonstantinou