KASSERT(9): add assertion message guidelines

[mhorne]

Summary

Add some text describing how to create useful assertion messages.

Improve and add to the EXAMPLES.

[emaste]

This looks good to me

share/man/man9/KASSERT.9

93

I think retconning MPASS to "must pass" is fine, but I assume it originated as multiprocessor assert -- @jhb?

[emaste]

share/man/man9/KASSERT.9

93

For reference MPASS originated in rG:0384fff8c5b09

[jhb]

I really wish we could transition KASSERT gracefully to using __VA_ARGS__ and away from the nested ()'s, but I'm not sure of a good way to permit both syntaxes concurrently.

share/man/man9/KASSERT.9

93

Yes, it came from BSD/OS as "multi-processor assert".

[imp]

In D44434#1013310, @jhb wrote:

I really wish we could transition KASSERT gracefully to using __VA_ARGS__ and away from the nested ()'s, but I'm not sure of a good way to permit both syntaxes concurrently.

I had a student use an interesting mix of _Generic and VA_ARGS to accomplish similar things, but you'd have to make some assumption... I'll see if I can tweak something...

[imp]

share/man/man9/KASSERT.9

5

2023-2024 please.

81

I wish we had a variation that would always be on, for tests that are super cheap... We have NASSERT at work, but the N I think is for Netflix not something clever.

93

I read it as Must Pass, even though I know its some MP thing... Maybe just note its BSD/OS + Multi-processor history with a ret-con to must pass :)

107

Do we want to add explicitly they should be useful without the result core file?

[bz]

Thank you!
Can we also adjust the comment above MPASS() in the header file?

share/man/man9/KASSERT.9

184

\n

[mhorne]

Handle minor review feedback.

[mhorne]

In D44434#1013418, @bz wrote:

Thank you!
Can we also adjust the comment above MPASS() in the header file?

Great point, handled in D44438.

share/man/man9/KASSERT.9

93

Now captured in D44439.

107

Good suggestion, I have incorporated this.

184

Not required for KASSERT.