Re: [fricas/fricas] bff708: Improve documentation

[Ralf Hemmecke]

Dear Waldek,

when I look at your doc-changes, I wonder whether you want to make

++ Description:

a "keyword" to introduce predocs, i.e. ++ docscring that come before the
actual object to document. In that case, I would prefer, if SPAD gets
closer to Aldor in using triple + (+++) as predoc and double + (++) as
postdoc.

Ralf

On 7/21/25 21:24, hebisch wrote:
> Branch: refs/heads/master
> Home: https://github.com/fricas/fricas
> Commit: bff70874e89fc82a01110ec22b178acc1f039dee
> https://github.com/fricas/fricas/commit/bff70874e89fc82a01110ec22b178acc1f039dee
> Author: Waldek Hebisch <c...@fricas.org>
> Date: 2025-07-21 (Mon, 21 Jul 2025)
>
> Changed paths:
> M src/algebra/amodgcd.spad
> M src/algebra/cden.spad
> M src/algebra/charpol.spad
> M src/algebra/computil.spad
> M src/algebra/cyldec.spad
> M src/algebra/evalut.spad
> M src/algebra/ffact.spad
> M src/algebra/flopak.spad
> M src/algebra/fops.spad
> M src/algebra/fortout.spad
> M src/algebra/fspace.spad
> M src/algebra/galfact.spad
> M src/algebra/intden.spad
> M src/algebra/intfact.spad
> M src/algebra/intrf.spad
> M src/algebra/lodof2.spad
> M src/algebra/mantepse.spad
> M src/algebra/mrv_limit.spad
> M src/algebra/muldep.spad
> M src/algebra/pscat.spad
> M src/algebra/rdeefx.spad
> M src/algebra/serexp.spad
> M src/algebra/skpol.spad
> M src/algebra/ssolve.spad
> M src/algebra/u32vec.spad
> M src/algebra/xpfact.spad
>
> Log Message:
> -----------
> Improve documentation
>
>
>
> To unsubscribe from these emails, change your notification settings at https://github.com/fricas/fricas/settings/notifications

[Waldek Hebisch]

On Mon, Jul 21, 2025 at 10:42:59PM +0200, 'Ralf Hemmecke' via FriCAS - computer algebra system wrote:
> Dear Waldek,
>
> when I look at your doc-changes, I wonder whether you want to make
>
> ++ Description:
>
> a "keyword" to introduce predocs, i.e. ++ docscring that come before the
> actual object to document. In that case, I would prefer, if SPAD gets closer
> to Aldor in using triple + (+++) as predoc and double + (++) as postdoc.

The issue is different. Top level per constructor documentation part
may contain several fields and they get different handling. Without
field indicator current handling was subtly wrong. If you add
another field, but keep description without field indicater, then
handling becomes badly wrong. We could try to make documentation
processing smarter, to get correct results in such cases. But
ATM I decided to stick to current formatting rules. In particualar
to have field indicator (that is "Description:") for description
field.

I remember you suggestion of using +++. But ATM current code
correctly resolves attachement of ++ comment (that is I am not
aware of any cases of wrong attachement). But there were issues
within toplevel documentatin hunk and I a trying to fix observed
problems.

BTW: The description part normally is last field. I think
some field(s) could go after it, but putting most fields
after description leads to wrong result.

--
Waldek Hebisch