[Teem-commit] SF.net SVN: teem:[7558] teem/trunk/src/biff/0-README .md

[<kin...@us...>]

Revision: 7558
          http://sourceforge.net/p/teem/code/7558
Author:   kindlmann
Date:     2025-10-01 15:17:29 +0000 (Wed, 01 Oct 2025)
Log Message:
-----------
writing tweaks

Modified Paths:
--------------
    teem/trunk/src/biff/0-README.md

Modified: teem/trunk/src/biff/0-README.md
===================================================================
--- teem/trunk/src/biff/0-README.md	2025-10-01 00:32:20 UTC (rev 7557)
+++ teem/trunk/src/biff/0-README.md	2025-10-01 15:17:29 UTC (rev 7558)
@@ -1,6 +1,6 @@
 # All about `/* Biff: */` annotations (new with Teem v2)
 
-Teem uses its `biff` library to collect error messages (based on its use in 90s skater culture to mean a hard fall). `biff` is not thread-safe, but that has never been the biggest barrier to its use (or Teem's use in general). Instead, a bigger problem is that there's nothing a function type signature that advertises whether it uses `biff` at all, or what return values from the function indicate the error conditions that would have generated `biff` messages that need to be collected and passed along to the user. Thankfully, there are now some automated tools to help with this.
+Teem uses its `biff` library to collect error messages (based on 90s skater culture using "biff" to mean a hard fall). `biff` is not thread-safe, but that has never been the biggest barrier to its use (or Teem's use in general). Instead, a bigger problem is that there's nothing in a function type signature that advertises whether it uses `biff` at all, or what return values from the function indicate the error conditions that would have generated `biff` messages that need to be collected and passed along to the user. Thankfully, there are now some semi-automated tools to help with this.
 
 `teem/src/_util/scan-symbols.py -biff` (which performs something that for no good reason started being called the "biff auto-scan") will scrutinize Teem source code to look at how it uses `biff`. This analysis creates parsable annotations of function definitions to automate whether and how `biffGetDone` is called in response to an error (in, say, a Python wrapper), as documented below.
 
@@ -30,7 +30,7 @@
 
 #### Required:
 
-- `<val>` : The return value `<val>` indicates a biff-reported error, i.e., if the function returns `<val>` then someone needs to retrieve the biff error message. `<val>` must not contain `|`, `:`, or whitespace, and cannot be `nope` or `maybe`. `<val>` is just a string (since it is in a comment), but hopfully it is parsable as the function return type (on this same line, before the comment containing this annotation). Simple integers are easy, but it could get trickier: example returns (currently used in Teem) include NULL, EOF, AIR\*FALSE, AIR_NAN, UINT_MAX, Z_STREAM_ERROR, and nrrdField_unknown. The point is: be prepared to do some work if you're trying to parse and act on Biff annotations.
+- `<val>` : The return value `<val>` indicates a biff-reported error, i.e., if the function returns `<val>` then someone needs to retrieve the biff error message. `<val>` must not contain `|`, `:`, or whitespace, and cannot be `nope` or `maybe`. `<val>` is just a string (since it is in a comment), but hopfully it is parsable as the function return type (on this same line, before the comment containing this annotation). Simple integers are easy, but it could get trickier: example returns (currently used in Teem) include `NULL`, `EOF`, `AIR\_FALSE`, `AIR\_NAN`, `UINT_MAX`, `Z_STREAM_ERROR`, and `nrrdField_unknown`. The point is: be prepared to do some work if you're trying to parse and act on Biff annotations.
 - or `<v1>|<v2>` : A return value of either `<v1>` or `<v2>` indicates an error has been recorded in `biff`
 - or `<v1>|<v2>|<v3>` : Error values are `<v1>` or `<v2>` or `<v3>` (and so on)
 - or `maybe:<N>:<val>` : This function uses something like `biffMaybeAddf()`, which may or may not set a biff error message, depending on the value of one of the function parameters (always called `useBiff`, as enforced by biff auto-scan). `useBiff` is the Nth function parameter, in the _1_-based numbering of the function parameters.

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.