search

Goddard-Fortran-Ecosystem / pFUnit

Parallel Fortran Unit Testing Framework
Other
172 stars 45 forks source link

Clarify status of documentation and examples #361

Closed tlestang closed 2 years ago

tlestang commented 2 years ago

It is unclear to me what is the best way to learn about the features available in pFUnit, and how to use them. In terms of available documentation, I can list

Having the demos is really useful, but do they describe the entirety of what is possible with the framework? If no, are there any other ressources available - for instance looking for a description of the available @assert decorators?

tclune commented 2 years ago

Yeah - documentation is not my strong suit. The demos were meant to grow to be more exhaustive, but that has not happened.

For the older style assertions @assertEqual() and such, you can look in the source and see the various interfaces at the top of the files in ./src/funit/asserts. Must should be suggestive. You can also infer a fair bit from this snippet of python in the parser: https://github.com/Goddard-Fortran-Ecosystem/pFUnit/blob/26ac761630dd3012081d67ce03ee99bff2dbe8d9/bin/funit/pFUnitParser.py#L18-L24 This is possibly incomplete, but if so, not by much.

Then for the newer style "hamcrest" @assert_that() style, it is more about composing things. The "matchers" are all in ./src/funit/fhamcrest, but some of the files there are infrastructure. It might be useful for me to create a subdirectory with the individual options.

And of course, I can usually respond fairly quickly with easy questions. So if you have a few types of assertions that you'd like to make I can quickly rattle off how to do them (or tell you that pfunit lacks such features).

tlestang commented 2 years ago

Thank you for the quick reply. I'll have a look at the parser then.

Yeah - documentation is not my strong suit.

Looks like you are maintaining/developing the framework mostly on your own. I appreciate this must be a lot of work - exhaustive and up to date docs is maybe a lot to ask.. I'm working on a unit test suite for a Fortran CFD framework (xcompact3d). This might take a while but hopefully we can contribute back examples and documentation for the features of pFUnit we end up using.

tclune commented 2 years ago

Yes - mostly on my own. OTOH it's pretty stable these days. And while I frequently use pFUnit in my other work, it already does what I need, and I (usually) know what it can and can't already do.

There have been other documentation efforts. There have been 2 major efforts. The first was when I had some funding, but it is now very obsolete. The other was with a private company that was developing documentation for a customer and chose not to contribute the documentation to the repo. Unfortunate, but I understand their reasoning.