more bort tests, some documentation fixes, some misc tests

[edwardhartnett]

Part of #381
Part of #397

Testing more borts().

[jbathegit]

Once again for the record, IMO the removal of all of this whitespace makes the docblock a lot less readable. Not everyone relies on just the rendered html from Doxygen for documentation - some of us still occasionaly edit the actual library routines and read it there.

[jbathegit]

We've always taken care to explicitly call this the "bit-wise representation of the FXY value", rather than just an "integer FXY value".

For example, if the character representation of the descriptor is "063022", then one could wrongly assume that the corresponding "integer FXY value" is just 63022, but instead what we're really talking about here is a value of 16150. See the remarks in the docblock for ifxy() for a detailed example.

Bottom line, there's a reason we've always referred to the latter value as the "bit-wise representation of the FXY value" throughout the entire library, rather than just the "integer FXY value" :-)

[edwardhartnett]

OK, the problem is that "bit-wise representation of the FXY value" is quite confusing. Even with your explanation, I don't understand the different between 63022 and 16150. Let's discuss at the meeting today...

[jbathegit]

BTW, I noticed in the developer CI run that a number of your new ufbstp tests were failing due to a SIGSEGV, rather than failing within the bort routine like we want:

Program received signal SIGSEGV: Segmentation fault - invalid memory reference.

Also, at least two new tests are failing with memory leaks:

1: ==6968==ERROR: LeakSanitizer: detected memory leaks
1: 
1: Direct leak of 32 byte(s) in 1 object(s) allocated from:
1:     #0 0x7fb0dc424867 in __interceptor_malloc ../../../../src/libsanitizer/asan/asan_malloc_linux.cpp:145
1:     #1 0x7fb0dc0b7ef8  (/lib/x86_64-linux-gnu/libgfortran.so.5+0x22ef8)
1: 
1: Indirect leak of 512 byte(s) in 1 object(s) allocated from:
1:     #0 0x7fb0dc424867 in __interceptor_malloc ../../../../src/libsanitizer/asan/asan_malloc_linux.cpp:145
1:     #1 0x7fb0dc0b7ef8  (/lib/x86_64-linux-gnu/libgfortran.so.5+0x22ef8)
1: 
1: SUMMARY: AddressSanitizer: 544 byte(s) leaked in 2 allocation(s).

Of course it can be really hard to notice these things with test_bort, since the roles are reversed and a fail now gets interpreted as a pass. So I think we really need to get in the habit of digging through the developer run output to check for these.

[edwardhartnett]

OK, let's separate the bort testing from the documentation changes, in order to divide and conquer this PR. ;-)

I have put the tests (after fixing the ufbstp() seg faults) in new PR #422 .

Once those are merged I will circle around again to this PR. We will have a documentation meeting today to discuss some of the issues with the documentation changes in this PR.

[edwardhartnett]

The testing work in the PR has been submitted in #422

We will discuss some documentation issues at today's meeting, and then I will resumbit some of the documentation work as future PRs...