cln_plugin: Add documentation

plugins/src/options.rs

@@ -1,3 +1,135 @@
+//! This module contains all logic related to `ConfigOption`'s that can be
+//! set in Core Lightning. The [Core Lightning documentation](https://docs.corelightning.org/reference/lightningd-config)
+//! describes how the user can specify configuration. This can be done using
+//! a command-line argument or by specifying the value in the `config`-file.
+//!
+//! ## A simple example
+//!
+//! A config option can either be specified using helper-methods or explicitly.
+//!
+//! ```no_run
+//! use anyhow::Result;
+//!
+//! use cln_plugin::ConfiguredPlugin;
+//! use cln_plugin::Builder;
+//! use cln_plugin::options::{StringConfigOption, DefaultStringConfigOption};
+//!
+//! const STRING_OPTION : StringConfigOption =
+//!     StringConfigOption::new_str_no_default(
+//!         "string-option",
+//!         "A config option of type string with no default"
+//! );
+//!
+//! const DEFAULT_STRING_OPTION : DefaultStringConfigOption =
+//!     DefaultStringConfigOption::new_str_with_default(
+//!         "string-option",
+//!         "bitcoin",
+//!         "A config option which uses 'bitcoin when as a default"
+//! );
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<()>{
+//!     let configured_plugin = Builder::new(tokio::io::stdin(), tokio::io::stdout())
+//!         .option(STRING_OPTION)
+//!         .option(DEFAULT_STRING_OPTION)
+//!         .configure()
+//!         .await?;
+//!     
+//!     let configured_plugin :ConfiguredPlugin<(),_,_> = match configured_plugin {
+//!         Some(plugin) => plugin,
+//!         None => return Ok(())       // Core Lightning was started with --help
+//!     };
+//!
+//!     // Note the types here.
+//!     // In `string_option` the developer did not specify a default and `None`
+//!     // will be returned if the user doesn't specify a configuration.
+//!     //
+//!     // In `default_string_option` the developer set a default-value.
+//!     // If the user doesn't specify a configuration the `String` `"bitcoin"`
+//!     // will be returned.
+//!     let string_option : Option<String> = configured_plugin
+//!         .option(&STRING_OPTION)
+//!         .expect("Failed to configure option");
+//!     let default_string_option : String = configured_plugin
+//!         .option(&DEFAULT_STRING_OPTION)
+//!         .expect("Failed to configure option");
+//!
+//!     // You can start the plugin here
+//!     // ...
+//!
+//!     Ok(())
+//! }
+//!
+//! ```
+//!
+//! ## Explicit initialization
+//!
+//! A `ConfigOption` can be initialized explicitly or using one of the helper methods.
+//! The two code-samples below are equivalent. The explicit version is more verbose
+//! but allows specifying additional information.
+//!
+//! ```
+//! use cln_plugin::options::{StringConfigOption};
+//!
+//! const STRING_OPTION : StringConfigOption = StringConfigOption {
+//!     name : "string-option",
+//!     default : (), // We provide no default here
+//!     description : "A config option of type string that takes no default",
+//!     deprecated : false,     // Option is not deprecated
+//! };
+//! ```
+//!
+//! ```
+//! use cln_plugin::options::{StringConfigOption};
+//! // This code is equivalent
+//! const STRING_OPTION_EQ : StringConfigOption = StringConfigOption::new_str_no_default(
+//!     "string-option-eq",
+//!     "A config option of type string that takes no default"
+//! );
+//! ```
+//!
+//! ## Required options
+//!
+//! In some cases you want to require the user to specify a value.
+//! This can be achieved using [`crate::ConfiguredPlugin::disable`].
+//!
+//! ```no_run
+//! use anyhow::Result;
+//!
+//! use cln_plugin::ConfiguredPlugin;
+//! use cln_plugin::Builder;
+//! use cln_plugin::options::{IntegerConfigOption};
+//!
+//! const WEBPORTAL_PORT : IntegerConfigOption = IntegerConfigOption::new_i64_no_default(
+//!     "webportal-port",
+//!     "The port on which the web-portal will be exposed"
+//! );
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<()> {
+//!     let configured_plugin = Builder::new(tokio::io::stdin(), tokio::io::stdout())
+//!         .option(WEBPORTAL_PORT)
+//!         .configure()
+//!         .await?;
+//!
+//!     let configured_plugin :ConfiguredPlugin<(),_,_> = match configured_plugin {
+//!         Some(plugin) => plugin,
+//!         None => return Ok(())       // Core Lightning was started with --help
+//!     };
+//!
+//!     let webportal_port : i64 = match(configured_plugin.option(&WEBPORTAL_PORT)?) {
+//!         Some(port) => port,
+//!         None => {
+//!             return configured_plugin.disable("No value specified for webportal-port").await
+//!         }
+//!     };
+//!
+//!     // Start the plugin here
+//!     //..
+//!
+//!     Ok(())
+//! }
+//! ```
 use serde::ser::Serializer;
 use serde::Serialize;
 
@@ -11,12 +143,18 @@ pub mod config_type {
     pub struct Flag;
 }
 
+
+/// Config values are represented as an i64. No default is used
 pub type IntegerConfigOption<'a> = ConfigOption<'a, config_type::Integer>;
+/// Config values are represented as a String. No default is used.
 pub type StringConfigOption<'a> = ConfigOption<'a, config_type::String>;
+/// Config values are represented as a boolean. No default is used.
 pub type BooleanConfigOption<'a> = ConfigOption<'a, config_type::Boolean>;
-
+/// Config values are repsentedas an i64. A default is used
 pub type DefaultIntegerConfigOption<'a> = ConfigOption<'a, config_type::DefaultInteger>;
+/// Config values are repsentedas an String. A default is used
 pub type DefaultStringConfigOption<'a> = ConfigOption<'a, config_type::DefaultString>;
+/// Config values are repsentedas an bool. A default is used
 pub type DefaultBooleanConfigOption<'a> = ConfigOption<'a, config_type::DefaultBoolean>;
 /// Config value is represented as a flag
 pub type FlagConfigOption<'a> = ConfigOption<'a, config_type::Flag>;