Improve support for annotations

[thomas-bc]

It could be useful to formalize the system where we use annotations for specific downstream processing. We have a few examples where we've built on top of the annotation system to do some custom post-FPP processing (e.g. subtopology parametarization back in they day, fprime-python, etc.).
But how each implementation used this is very ad-hoc.

An example could be:

@ My annotation
@!decorated_value
struct MySuperStruct {
    x: U32
}

And you'd get in the model

// pseudocode
MySuperStruct {
   annotation: "My annotation\n!decorated_value"
   decorators: ["decorated_value"]
}

[SterlingPeet]

@zeroping

[zeroping]

One barrier has been that the annotations are the only place we can put extra info, and without structure, those annotations are pulled in (concatenated together) and used by the autocoder in some places that might not make sense for these non-documentation annotations. Something like the above @! style above seems like a nice way to distinguish regular annotations vs 'structured annotations' (or whatever we call them).

A suggestion: could we standardize on a format for the structure of the start of a 'structured annotation'? Maybe define these as starting with '@!', then a non-whitespace keyword, and an open format for the remainder of the line from there?

Just to get some brainstorming down, here are a few examples of kinds of additional things I've wished for, which could use some extra info in the FPP:

• Attaching units of measurements to a telemetry channel or command parameter (for GDS)
  • ex: !@units: m/s
• Marking commands as "unsafe" or needing a two-stage confirmation (GDS use, or in coordination with FSW)
  • ex: !@unsafe or !@groundUseOnly
• Applying linear transform to channels / parameters (ex: a mapping between SI units and engineering units, GSE use, maybe with FSW)
  • ex: !@scale: 0.25 and !@offset: 273.15
  • Does it make sense to try to support some sort of clustering of related annotations?
• Marking a telemetry channel as a counter, and modifying the autocoder's output with extra functionality (FSW side)
• Limits on command parameter or parameter numeric ranges
  • Somewhat inspired via paramSet_* Handlers fprime#4915

So, yes, I'm liking the direction this is going.

[Kronos3]

@thomas-bc Is this feature request asking just for a system to formalize/extract decorators or also specify a standard set of decorators? I think both are valuable but maybe we should just start with the former. The latter is simple since we can just push to the spec and not touch the implementation.

[thomas-bc]

Yes this would definitely be for the former at first.

[bocchino]

These are good ideas. I think the first step is to develop a list of kinds of annotations; then we can propose a syntax for differentiating the kinds. For example, maybe ! directly after @ could indicate "this line is for the analyzer" and then whatever follows the ! could provide further instructions on which analysis to use.

I have always had the idea that annotations could be made much more powerful. For example, there could be a contract between the annotation writer and the analyzer where the annotation writer provides a custom parser and generates AST nodes indicating which nodes are expressions and type names; then the FPP analyzer could resolve the expressions and type names and pass the results back to the custom analysis. That way you could leverage the FPP analyzer to implement custom DSLs inside the annotations. So for example instead of just saying @!offset = 3 you could write an FPP constant constant OFFSET = 3 and then in the annotation say @! offset = expr(OFFSET), and expr(OFFSET) would be resolved to 3, just as in regular FPP. The custom DSL would still need some analysis support, but a lot of the heavy lifting (e.g., symbol resolution, basic type checking) could be handled by the FPP analyzer.

We could also provide a set of parsers for standard patterns, such as key-value pairs, so users don't have to write their own parsers if they're satisfied with those patterns.

As far as how to represent the analysis results, instead of using a "decorator class" I think we should use maps. This is how we represent all analysis results in FPP, and it's very flexible and composable. Each new kind of analysis can be represented as a new map that maps AST nodes to analysis results for each node (if any). That way you can add as many new kinds of analysis as you like without changing anything in the standard FPP code.