Thank you for writing this Jordan, I agree that there should be one standard way to document, which we can point to as good default.
I think whatever solution we come up with, it has to be discoverable from pursuit documentation page and source page.
Let’s take Aff Bus as an example. Currently it support only Text based documentation. So if we modify source code to point to example or test it could look like this in pursuit and source code.
If we let it be in the project, it can be checked and maintain with version. Easy to discover from documentation page and even from the code. Basically you would not have to go for a hunt elsewhere.
My point is if there is great documentation with examples explanation somewhere else, and you cannot find it, then it doesn’t matter. Like it doesn’t exist.
I just made example of the links, the looks can be changed if needed. Comments example type and comment test type would need to be added to compiler, and symbols chosen to be anything.
These are just my suggestions, if you don’t like them, ignore them. No feelings being hurt.