Spicy: Support additional documentation tags inside EVT files.

So far we had trouble documenting Spicy analyzers through Zeekygen
because they would show up as components belonging to the
`Zeek::Spicy` plugin; whereas traditional analyzers would be their own
plugins and hence documented individually on their own. This commit
teaches Zeekygen to track Spicy analyzers separately inside their own
`Info` instances. This information isn't further used in this commit
yet, but will be merged with the plugin output in a subsequent change
to get the expected joint output.

To pass additional information to Zeekygen, EVT files now also support
two new tags for Zeekygen purposes:

- `%doc-id = ID;` defines the global ID under which everything inside
  the EVT file will be documented by Zeekygen, conceptually comparable
  to plugin names (e.g., `Zeek::Syslog`).

- `%doc-description = "text" provides additional text to go into the
  documentation (comparable to plugin descriptions).

This information is carried through into the HLTO runtime
initialization code, from where it's registered with Zeekygen.

This commit also removes a couple of previous hacks of how Spicy
integrated with Zeekygen which (1) ended up generating broken doc output
for Spicy components, and (2) don't seem to be necessary anymore
anyways.
This commit is contained in:
Robin Sommer 2023-09-18 11:16:51 +02:00
parent 7544aedb6a
commit 6f882af7cc
No known key found for this signature in database
GPG key ID: D8187293B3FFE5D0
11 changed files with 260 additions and 13 deletions

View file

@ -89,6 +89,12 @@ public:
using UsageError::UsageError;
};
/**
* Begins registration of a Spicy EVT module. All subsequent, other `register_*()`
* function call will be associated with this module for documentation purposes.
*/
void register_spicy_module_begin(const std::string& name, const std::string& description, const hilti::rt::Time& mtime);
/**
* Registers a Spicy protocol analyzer with its EVT meta information with the
* plugin's runtime.
@ -118,6 +124,13 @@ void register_packet_analyzer(const std::string& name, const std::string& parser
/** Registers a Spicy-generated type to make it available inside Zeek. */
void register_type(const std::string& ns, const std::string& id, const TypePtr& type);
/**
* Ends registration of a Spicy EVT module. This must follow a preceding
* `registerSpicyModuleBegin()`.
*/
void register_spicy_module_end();
/** Identifies a Zeek-side type. */
enum class ZeekTypeTag : uint64_t {
Addr,