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.

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;

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);
 }

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};

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,
   }
 }

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;
 

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};

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};
 

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;
 

application/apps/indexer/plugins_api/wit/v0.1.0/deps/shared/logging.wit

@@ -3,12 +3,17 @@ package chipmunk:[email protected];
 /// 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,
   }
 

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<string>),
@@ -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<string>,
+    /// 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<string>),
-    /// Drop-down input type with a list of selectable options.
+    /// Represents Drop-down input type with a list of selectable options.
     dropdown(list<string>)
   }
 }

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;

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;
 }