Regarding documentation of using fplll as a c++ library

[Rohan Kalra]

Hello everybody,

I recently used fplll as a c++ library for a project.

I found it a little difficult to look at the documentation and then try to find in the examples where the function or class was used to figure out ho to actually use it. I think it would be considerably easier for users if a snippet of the example or a short example of that function was given in the documentation itself.

Can I submit a more detailed proposal if you think this would actually be helpful.

Regards,

Rohan

[Martin R. Albrecht]

Hi Rohan,

I think the key challenge would be to automatically test those snippets. How do we make sure they’re actually (still) accurate?

Cheers,
Martin

--

_pgp: https://keybase.io/martinralbrecht
_www: https://malb.io
_prn: he/him or they/them

[Joe Rowell]

Hi Martin, all,

In the past, I've solved this issue by using doxygen's \snippet tag:

https://stackoverflow.com/a/16034375

It's not quite as nice as Python's doctests (the embedded file is only shown in the doxygen), but if you embed your unit tests as snippets then it's pretty close. Assuming the tests are kept up to date, then you get correctness for free.

Cheers,

Joe 

--
You received this message because you are subscribed to the Google Groups "fplll-devel" group.
To unsubscribe from this group and stop receiving emails from it, send an email to fplll-devel...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/fplll-devel/87il2cik8v.fsf%40googlemail.com.

[Rohan Kalra]

Hi,

I think it's a nice idea to use doxygen's \snippet tag and to keep the tests up to date we can do what sagemath does which is making changes in the documentation and examples in parallel with the changes in code.

If you think this is feasible we can work on a more detailed proposal which will help us better understand the challenges and find effective solutions for them.

Cheers,

Rohan

[Martin R. Albrecht]

Hi Rohan,

Perhaps you can send a GitHub PR with a minimal working example and we can take it from there?

Cheers,
Martin