Merge remote-tracking branch 'origin/topic/awelzel/ldap-follow-up'

* origin/topic/awelzel/ldap-follow-up:
  protocol/ldap: Add doc-id/doc-description to .evt file
  spicy/manager: Ensure Zeekygen knows identifier for registered types

CHANGES

@@ -1,3 +1,14 @@
+6.1.0-dev.531 | 2023-10-11 14:09:22 +0200
+
+  * protocol/ldap: Add doc-id/doc-description to .evt file (Arne Welzel, Corelight)
+
+  * spicy/manager: Ensure Zeekygen knows identifier for registered types (Arne Welzel, Corelight)
+
+    Without this, Zeekygen won't generate documentation about exported
+    enum types as it can not resolve the identifier. Also, only register a
+    type as item with the Spicy plugin if there's no _module_info currently
+    active.
+
 6.1.0-dev.528 | 2023-10-10 20:03:31 +0200
 
   * Introduce dedicated `LDAP::Info` (Benjamin Bannier, Corelight)

VERSION

@@ -1 +1 @@
-6.1.0-dev.528
+6.1.0-dev.531

doc

@@ -1 +1 @@
-Subproject commit a14ea840a1fc99cb925fac3a7f61961decd22ab0
+Subproject commit 6492aaeaca49ee434f03984af47310c70d96dafc

src/analyzer/protocol/ldap/ldap.evt

@@ -1,5 +1,8 @@
 # Copyright (c) 2021 by the Zeek Project. See LICENSE for details.
 
+%doc-id = Zeek::LDAP;
+%doc-description = "LDAP analyzer";
+
 protocol analyzer LDAP_TCP over TCP:
     parse with LDAP::Messages;
 

src/spicy/manager.cc

@@ -244,10 +244,13 @@ void Manager::registerType(const std::string& id, const TypePtr& type) {
     auto zeek_id = detail::install_ID(local.c_str(), ns.c_str(), true, true);
     zeek_id->SetType(type);
     zeek_id->MakeType();
-    AddBifItem(id, ::zeek::plugin::BifItem::TYPE);
+
+    detail::zeekygen_mgr->Identifier(zeek_id);
 
     if ( _module_info )
         _module_info->AddBifItem(id, ::zeek::plugin::BifItem::TYPE);
+    else
+        AddBifItem(id, ::zeek::plugin::BifItem::TYPE);
 }
 
 TypePtr Manager::findType(const std::string& id) const {
@@ -616,7 +619,7 @@ void Manager::InitPostScript() {
     for ( const auto& [name, id] : _events ) {
         if ( ! id->GetType() ) {
             auto args = make_intrusive<RecordType>(new type_decl_list());
-            auto et = make_intrusive<FuncType>(std::move(args), base_type(TYPE_VOID), FUNC_FLAVOR_EVENT);
+            auto et = make_intrusive<FuncType>(std::move(args), nullptr, FUNC_FLAVOR_EVENT);
             id->SetType(std::move(et));
         }
     }

testing/btest/Baseline/spicy.zeekygen-enum-zeek-side/output1

@@ -0,0 +1,3 @@
+### BTest baseline data generated by btest-diff. Do not edit. Use "btest -U/-u" to update. Requires BTest >= 0.63.
+[debug/zeek]   Got module's documentation name: Foo::Bar
+[debug/zeek]   Got module's documentation description: Just a "test" analyzer.h

testing/btest/Baseline/spicy.zeekygen-enum-zeek-side/output2

@@ -0,0 +1,45 @@
+### BTest baseline data generated by btest-diff. Do not edit. Use "btest -U/-u" to update. Requires BTest >= 0.63.
+.. _plugin-foo-bar:
+
+Foo::Bar
+--------
+
+Just a "test" analyzer.h
+
+Components
+++++++++++
+
+:zeek:enum:`Analyzer::ANALYZER_SPICY_MYSSH`
+
+Types
++++++
+
+.. zeek:type:: MySSH::Compression
+   :source-code: <...>/zeekygen-enum-zeek-side.zeek 19 25
+
+   :Type: :zeek:type:`enum`
+
+      .. zeek:enum:: MySSH::VERY MySSH::Compression
+
+         (present if :doc:`<...>/zeekygen-enum-zeek-side.zeek` is loaded)
+
+
+         Documentation of VERY
+
+      .. zeek:enum:: MySSH::DIFFERENT MySSH::Compression
+
+         (present if :doc:`<...>/zeekygen-enum-zeek-side.zeek` is loaded)
+
+
+         Documentation of DIFFERENT
+
+
+.. zeek:type:: MySSH::Encryption
+
+   :Type: :zeek:type:`enum`
+
+      .. zeek:enum:: MySSH::Encryption_NONE MySSH::Encryption
+
+      .. zeek:enum:: MySSH::Encryption_Undef MySSH::Encryption
+
+

testing/btest/Baseline/spicy.zeekygen-enum-zeek-side/output3

@@ -0,0 +1,9 @@
+### BTest baseline data generated by btest-diff. Do not edit. Use "btest -U/-u" to update. Requires BTest >= 0.63.
+MySSH::Compression, {
+MySSH::DIFFERENT,
+MySSH::VERY
+}
+MySSH::Encryption, {
+MySSH::Encryption_NONE,
+MySSH::Encryption_Undef
+}

testing/btest/Baseline/spicy.zeekygen/output2

@@ -11,6 +11,20 @@ Components
 
 :zeek:enum:`Analyzer::ANALYZER_SPICY_SSH`
 
+Types
++++++
+
+.. zeek:type:: SSH::Compression
+
+   :Type: :zeek:type:`enum`
+
+      .. zeek:enum:: SSH::Compression_NONE SSH::Compression
+
+      .. zeek:enum:: SSH::Compression_ZLIB SSH::Compression
+
+      .. zeek:enum:: SSH::Compression_Undef SSH::Compression
+
+
 Events
 ++++++
 

testing/btest/spicy/zeekygen-enum-zeek-side.zeek

@@ -0,0 +1,82 @@
+# @TEST-REQUIRES: have-spicy
+#
+# @TEST-EXEC: spicyz -D zeek -o test.hlto doc.spicy ./doc.evt >output 2>&1
+# @TEST-EXEC: cat output | grep 'module.s documentation' >output1
+# @TEST-EXEC: btest-diff output1
+#
+# @TEST-EXEC: unset ZEEK_DISABLE_ZEEKYGEN && zeek -X zeekygen.conf test.hlto %INPUT
+# @TEST-EXEC: cat protocol.rst  | sed -n '/_plugin-foo-bar/,/_plugin/p' | sed '$d' >output2
+# @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff output2
+#
+# @TEST-EXEC: zeek test.hlto %INPUT >output3
+# @TEST-EXEC: TEST_DIFF_CANONIFIER=$SCRIPTS/diff-remove-abspath btest-diff output3
+
+# @TEST-DOC: Enumeration Compression is exported in .evt file *and* defined on the Zeek side. Result in Zeekygen output is from the Zeek side. Encryption is only exported from Spicy.
+
+module MySSH;
+
+export {
+	type Compression: enum {
+		## Documentation of VERY
+		VERY = 0,
+		## Documentation of DIFFERENT
+		DIFFERENT = 1,
+	};
+
+	# Exported from Spicy
+	# type Encryption: enum { ... }
+}
+
+module GLOBAL;
+
+event zeek_init()
+	{
+	# Print enum_names() of the involved types, too.
+	print MySSH::Compression, enum_names(MySSH::Compression);
+	print MySSH::Encryption, enum_names(MySSH::Encryption);
+	}
+
+
+# @TEST-START-FILE doc.spicy
+
+module MySSH;
+
+import zeek;
+
+public type Compression = enum {
+    NONE = 0,
+    ZLIB = 1,
+};
+
+public type Encryption = enum {
+    NONE = 0,
+};
+
+public type Banner = unit {
+    magic   : /SSH-/;
+    version : /[^-]*/;
+    dash    : /-/;
+    software: /[^\r\n]*/;
+};
+# @TEST-END-FILE
+
+# @TEST-START-FILE doc.evt
+
+%doc-id = Foo::Bar;
+%doc-description = "Just a \"test\" analyzer.h";
+
+protocol analyzer spicy::MySSH over TCP:
+    parse originator with MySSH::Banner,
+    port 22/tcp,
+    replaces SSH;
+
+export MySSH::Compression;  # This one also exists on the Zeek side
+
+export MySSH::Encryption;
+
+
+# @TEST-END-FILE
+
+# @TEST-START-FILE zeekygen.conf
+proto_analyzer	*	protocol.rst
+

testing/btest/spicy/zeekygen.zeek

@@ -22,6 +22,11 @@ module SSH;
 
 import zeek;
 
+public type Compression = enum {
+    NONE = 0,
+    ZLIB = 1,
+};
+
 public type Banner = unit {
     magic   : /SSH-/;
     version : /[^-]*/;