From 2eac9b018f2d186e839ce0efc649302b2c9810bd Mon Sep 17 00:00:00 2001 From: Ammar Abou Zor Date: Thu, 23 Jan 2025 10:36:19 +0100 Subject: [PATCH] Plugins: API Documentations & Cleanup * Document all modules and types in the public API of the plugins_api crate * Small improvements for the wit files. * Fix warnings in bytesource tests. --- .../indexer/plugins_api/src/shared/mod.rs | 2 +- .../imp_bytesource_diff_mod_pass.rs | 2 -- .../wit/v0.1.0/deps/bytesource/bytesource.wit | 1 + .../wit/v0.1.0/deps/bytesource/types.wit | 9 ++++- .../wit/v0.1.0/deps/bytesource/world.wit | 3 ++ .../wit/v0.1.0/deps/parser/parser.wit | 1 + .../wit/v0.1.0/deps/parser/types.wit | 1 + .../wit/v0.1.0/deps/parser/world.wit | 3 ++ .../wit/v0.1.0/deps/shared/logging.wit | 7 +++- .../wit/v0.1.0/deps/shared/shared-types.wit | 36 ++++++++++++++++--- .../wit/v0.1.0/deps/shared/world.wit | 3 ++ .../indexer/plugins_api/wit/v0.1.0/world.wit | 8 ++--- 12 files changed, 62 insertions(+), 14 deletions(-) diff --git a/application/apps/indexer/plugins_api/src/shared/mod.rs b/application/apps/indexer/plugins_api/src/shared/mod.rs index dab66fa8e..270e11ff0 100644 --- a/application/apps/indexer/plugins_api/src/shared/mod.rs +++ b/application/apps/indexer/plugins_api/src/shared/mod.rs @@ -1,4 +1,4 @@ -//! TODO AAZ: Docs and verify the final pubic API before changing the host. +//! Provides shared types to be used among all other plugins. pub mod logging; pub mod plugin_logger; diff --git a/application/apps/indexer/plugins_api/tests/bytesource_macro/imp_bytesource_diff_mod_pass.rs b/application/apps/indexer/plugins_api/tests/bytesource_macro/imp_bytesource_diff_mod_pass.rs index e8d03ddbe..f10bdac53 100644 --- a/application/apps/indexer/plugins_api/tests/bytesource_macro/imp_bytesource_diff_mod_pass.rs +++ b/application/apps/indexer/plugins_api/tests/bytesource_macro/imp_bytesource_diff_mod_pass.rs @@ -32,8 +32,6 @@ mod impl_mod { // Module for export macro mod export_mod { use super::Dummy; - use plugins_api::bytesource::*; - use plugins_api::*; plugins_api::bytesource_export!(Dummy); } diff --git a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/bytesource/bytesource.wit b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/bytesource/bytesource.wit index ce210ac19..8819d3638 100644 --- a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/bytesource/bytesource.wit +++ b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/bytesource/bytesource.wit @@ -1,5 +1,6 @@ package chipmunk:bytesource@0.1.0; +/// The definitions which must be provided by the byte-source plugins. interface byte-source { use chipmunk:shared/shared-types@0.1.0.{version, init-error, config-item, config-schema-item}; use bytesource-types.{source-config, source-error}; diff --git a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/bytesource/types.wit b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/bytesource/types.wit index 8c7545e5a..e80c11803 100644 --- a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/bytesource/types.wit +++ b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/bytesource/types.wit @@ -1,23 +1,30 @@ package chipmunk:bytesource@0.1.0; +/// Contains the types definitions used for the development of byte-source plugins. interface bytesource-types { use chipmunk:shared/logging@0.1.0.{level}; /// Represents the addresses defining a network socket record socket-info { + /// The IP of the socket info represented as string. ip: string, + /// The port of the socket info represented as 16 bits unsigned integer. port: u16, } /// Represents the errors while reading bytes in bytesource plugin variant source-error { + /// Errors happened around IO operations. io(string), - unsupported, + /// Errors represents an unsupported interface by the plugin. + unsupported(string), + /// Other kind of errors with custom string message. other(string), } /// General configurations related to all bytesources record source-config { + /// Represent the current log level running in Chipmunk app. log-level: level, } } diff --git a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/bytesource/world.wit b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/bytesource/world.wit index fcc06465a..81d30ba73 100644 --- a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/bytesource/world.wit +++ b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/bytesource/world.wit @@ -1,5 +1,8 @@ package chipmunk:bytesource@0.1.0; +/// World represent the relation between interfaces for the byte-source plugins. +/// It contains the provided type definitions besides the interfaces that must be +/// implemented with the byte-sources plugins. world bytesource { import chipmunk:shared/logging@0.1.0; diff --git a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/parser/parser.wit b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/parser/parser.wit index 9315f8f65..f4cee6f05 100644 --- a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/parser/parser.wit +++ b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/parser/parser.wit @@ -1,5 +1,6 @@ package chipmunk:parser@0.1.0; +/// The definitions which must be provided by the parser plugins. interface parser { use chipmunk:shared/shared-types@0.1.0.{version, init-error, config-item, config-schema-item}; use parse-types.{render-options, parser-config, parse-return, parse-error}; diff --git a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/parser/types.wit b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/parser/types.wit index cff4f29dd..27edd2c7e 100644 --- a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/parser/types.wit +++ b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/parser/types.wit @@ -1,5 +1,6 @@ package chipmunk:parser@0.1.0; +/// Contains the types definitions used for the development of parser plugins. interface parse-types { use chipmunk:shared/logging@0.1.0.{level}; diff --git a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/parser/world.wit b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/parser/world.wit index 354ea36b2..6db74583a 100644 --- a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/parser/world.wit +++ b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/parser/world.wit @@ -1,5 +1,8 @@ package chipmunk:parser@0.1.0; +/// World represent the relation between interfaces for the parser plugins. +/// It contains the provided type definitions besides the interfaces that must be +/// implemented with the parser plugins. world parse { import chipmunk:shared/logging@0.1.0; diff --git a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/shared/logging.wit b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/shared/logging.wit index 7e3055037..fe2efb5a9 100644 --- a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/shared/logging.wit +++ b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/shared/logging.wit @@ -3,12 +3,17 @@ package chipmunk:shared@0.1.0; /// Logging definitions and methods for all plugins interface logging { - /// Log Level + /// The definitions of the log Level enum level { + /// Represents error log level error, + /// Represents warn log level warn, + /// Represents info log level info, + /// Represents debug log level debug, + /// Represents trace log level trace, } diff --git a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/shared/shared-types.wit b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/shared/shared-types.wit index f9160b77f..3fab3323f 100644 --- a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/shared/shared-types.wit +++ b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/shared/shared-types.wit @@ -5,30 +5,46 @@ interface shared-types { /// Represents a semantic version. record version { + /// The major part of semantic version. major: u16, + /// The minor part of semantic version. minor: u16, + /// The patch part of semantic version. patch: u16, } /// Error type while initializing the plugins variant init-error { + /// Errors related to the provided configurations to the plugin. config(string), + /// Errors happened around IO operations. io(string), + /// Errors represents an unsupported interface by the plugin. unsupported(string), + /// Other kind of errors with custom string message. other(string), } - /// Represents a configuration item, which includes an identifier and its corresponding value. + /// Represents a configuration item, that will be provided to the plugin in the + /// initialization function. record config-item { + /// The identifier of the configuration item. This ID must match the one provided in + /// `config-schema-item` id: string, + /// The corresponding value of the configuration with the provided ID. + /// The value type matches the type define in `config-schema-item` with the same ID. value: config-value, } /// Represents the value of a configuration item. variant config-value { + /// Represents boolean value. boolean(bool), + /// Represents numerical integer value. integer(s32), + /// Represents numerical floating value. float(f32), + /// Represents text value. text(string), /// List of strings representing directory paths. directories(list), @@ -38,25 +54,35 @@ interface shared-types { dropdown(string) } - /// Represents the schema for a configuration item. + /// Represents the schema for a configuration item, which should be provided from the plugins + /// to define their configuration that needed to be set by the users. record config-schema-item { + /// The identifier of the configuration schema item. This ID will match the one provided in + /// `config-item` id: string, + /// Title of the configuration item that will be presented to the users. title: string, + /// An optional short description of the configuration item that will be presented to the users. description: option, + /// Represent the type of the needed configuration value (boolean, string, path ...) input-type: config-schema-type, } /// Defines the possible input types for configuration schemas. variant config-schema-type { + /// Represents boolean type. boolean, + /// Represents numerical integer type. integer, + /// Represents numerical floating type. float, + /// Represents a text type. text, - /// A list of directories. + /// Represents a list of directories. directories, - /// A list of types with the given allowed file extensions (Empty to allow all). + /// Represents a list of types with the given allowed file extensions (Empty to allow all). files(list), - /// Drop-down input type with a list of selectable options. + /// Represents Drop-down input type with a list of selectable options. dropdown(list) } } diff --git a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/shared/world.wit b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/shared/world.wit index 9690ec483..67eb2616b 100644 --- a/application/apps/indexer/plugins_api/wit/v0.1.0/deps/shared/world.wit +++ b/application/apps/indexer/plugins_api/wit/v0.1.0/deps/shared/world.wit @@ -1,5 +1,8 @@ package chipmunk:shared@0.1.0; +/// This world contains the shared types among all other plugins, +/// and meant to be used to generate their bindings so they can be used +/// along all plugins. world bindings { import shared-types; import logging; diff --git a/application/apps/indexer/plugins_api/wit/v0.1.0/world.wit b/application/apps/indexer/plugins_api/wit/v0.1.0/world.wit index 219c05c43..c862944c8 100644 --- a/application/apps/indexer/plugins_api/wit/v0.1.0/world.wit +++ b/application/apps/indexer/plugins_api/wit/v0.1.0/world.wit @@ -1,9 +1,9 @@ package chipmunk:plugins; -world imports { - include chipmunk:shared/bindings@0.1.0; -} +// This file used as the top of the plugins packages and used only as the place +// where `generate!()` macro needs to point to, in order to resolve the relation +// between the packages. world bindings { - include imports; + include chipmunk:shared/bindings@0.1.0; }