It seems like one area where our documentation is sorely lacking is the weirds. Apart from comments in the code, I believe the only documentation is the name of the weird itself.
Is there a mechanism in Broxygen to document weirds? If not, has anyone thought about what such a mechanism might look like?
–Vlad
There’s not currently a mechanism. Things that Broxygen can easily aid in documenting are tied to a script-layer name/symbol/identifier. Weirds differ since they’re string values.
A suggestion would be to change weirds to use an enum instead of a string value. That would then provide an identifier to hang documentation off of and also maybe help keep the core-analyzers in sync w/ scripts (e.g. there’s currently not a robust way to signify to a user that a weird was removed/changed and thus their scripts may become stale or possibly broken in the case of a rename).
- Jon
Yeah, either that, or introducing a structured ID namespace (e.g.,
"http.client.unexpected_data"), potentially with some static analysis
to find IDs that aren't linked to docs.
In either case it would be nice if the scheme unified reporting weirds
from core and script land.
Robin
I was thinking of just a simple Weird::Type enum with comments, much like how the Notice documentation is generated. I do also like the thought of the structured namespace.
Maybe more generally, we should to make a Weird closer to a Notice. For example, if a file analyzer generates a weird, there are no fields in the weird.log to map it back to the offending file. I realize that that’s trickier, since Weirds can be generated from either the core or script-land.
–Vlad
Maybe more generally, we should to make a Weird closer to a Notice. For
example, if a file analyzer generates a weird, there are no fields in the
weird.log to map it back to the offending file.
Yeah, that would make a lot sense.
I realize that that's trickier, since Weirds can be generated from
either the core or script-land.
One thing to keep in mind is that it shouldn't become burdensome to
write the code for generating a Weird, in particular in core land. The
situations that they report are (supposedly) rare, so it's not worth
spending much time on. Right now, one appeal of the Weirds is that
it's to say "alright, shouldn't happen, weird() if it does"; but if
one would need to start building Vals etc. to pass the right
parameters with it, one might become more inclined to skip the check
(because it shouldn't happen anyways 
This is not a huge issue, and
could probably be solved with a few wrappers covering common cases
(and we have some of that already, like the WeirdConn() etc.; could
extend that a bit more).
Robin