Testing the example codes in the documentation

[Beliavsky]

An example I tried to run from the documentation, program demo_normal_pdf, has a typo

complx :: loc, scale

where complx should be complex.

Upon fixing this the code ran, as have other codes I have tried from the documentation. Is it possible to test all the codes in the online documentation in an automated way?

A comment there says

10 standard norml random variates

where "normal" is misspelled. Typos in comments probably need to be caught manually. Also "imaginary" is misspelled "imagainary".

More nitpicking -- some comments have text immediately after the !, which I think is less readable, for example

!a probability density at 1.0 in standard normal

It would be possible to check for ! not followed by a space.

[awvwgk]

For spelling there is actually a workflow in the repository which catches those and highlights them in the code review. So far those comments were mostly ignored, however.

Regarding testing, there is currently no way to automatically extract and compile the examples against stdlib. A workflow I'm usually using in my documentation setups is to have separate Fortran files which are part of the test suite and use a literal include for the documentation. Not sure how well this works with Ford, though.

[urbanjost]

Either direction works (extract tests from documentation or pull examples into documentation) (I pull from the documentation) but documentation code does need verified. For all the libraries I maintain it is a requirement to have a working example for each procedure in the documentation that is automatically extracted and placed in the example directory and built as well; it catches a of typoes, and makes sure there is a confidence test for each procedure at a minimum, in general (there are always exceptions). I convinced an employer long ago that all man-pages should have a working example and the customers were happier with the documentation, a LOT of typos in the originals were caught, the procedures became part of release QA because it provided quite good coverage, ... lots of benefits so I continue that practice even for my own little projects. I think it would be great if this was part of the practice with stdlib from the ground up; as an example is worth a thousand words.

It is a pet gripe of mine that the vast majority of Fortran descriptions of the intrinsics do not contain examples; I would hate to see that be the case with stdlib.