Merge pull request #651 from swimos/docs6

Tidy up of crate/module API: Stage 6

Author: horned-sphere

api/formats/swimos_recon/src/recon_parser/record/matcher/mod.rs

@@ -43,22 +43,22 @@ pub trait HeaderPeeler<'a>: Clone {
 
     /// Provide the name of the tag attribute.
     ///
-    /// #Arguments
+    /// # Arguments
     /// * `name` - The name of the tag. Note that this has a more restrictive lifetime as may
     /// have been unescaped by the parser.
     fn tag(self, name: &str) -> Result<Self, Self::Error>;
 
     /// Feed a slot from the body of the attribute.
     ///
-    /// #Arguments
+    /// # Arguments
     /// * `name` - The name of the slot. Note that this has a more restrictive lifetime as may
     /// have been unescaped by the parser.
     /// * `value` - Span of the input containing the Recon of the value of the slot.
     fn feed_header_slot(self, name: &str, value: Span<'a>) -> Result<Self, Self::Error>;
 
     /// Feed a value item from the body of the attribute.
     ///
-    /// #Arguments
+    /// # Arguments
     /// * `value` - Span of the input containing the Recon of the item
     fn feed_header_value(self, value: Span<'a>) -> Result<Self, Self::Error>;
 
@@ -68,7 +68,7 @@ pub trait HeaderPeeler<'a>: Clone {
 
     /// Attempt to interpret the attribute.
     ///
-    /// #Arguments
+    /// # Arguments
     /// * `body` - The remainder of the input span. Note that this is entirely uninterpreted and
     /// so may not contain valid Recon.
     fn done(self, body: Span<'a>) -> Result<Self::Output, Self::Error>;

api/swimos_agent_protocol/src/model.rs

@@ -155,8 +155,8 @@ pub struct AdHocCommand<S, T> {
 }
 
 impl<S, T> AdHocCommand<S, T> {
-    /// #Arguments
-    /// * `address` - The target lane for the the command.
+    /// # Arguments
+    /// * `address` - The target lane for the command.
     /// * `command` - The body of the command message.
     /// * `overwrite_permitted` - Controls the behaviour of command handling in the case of back-pressure.
     /// If this is true, the command maybe be overwritten by a subsequent command to the same target (and so

api/swimos_api/src/agent/mod.rs

@@ -196,7 +196,7 @@ pub trait AgentContext: Sync {
     fn ad_hoc_commands(&self) -> BoxFuture<'static, Result<ByteWriter, DownlinkRuntimeError>>;
 
     /// Add a new lane endpoint to the runtime for this agent.
-    /// #Arguments
+    /// # Arguments
     /// * `name` - The name of the lane.
     /// * `land_kind` - Kind of the lane, determining the protocol that the runtime uses
     /// to communicate with the lane.
@@ -214,7 +214,7 @@ pub trait AgentContext: Sync {
     ) -> BoxFuture<'static, Result<HttpLaneRequestChannel, AgentRuntimeError>>;
 
     /// Open a downlink to a lane on another agent.
-    /// #Arguments
+    /// # Arguments
     /// * `config` - The configuration for the downlink.
     /// * `host` - The host containing the node.
     /// * `node` - The node URI for the agent.
@@ -228,7 +228,7 @@ pub trait AgentContext: Sync {
     ) -> BoxFuture<'static, Result<(ByteWriter, ByteReader), DownlinkRuntimeError>>;
 
     /// Add a new named store that will persist a (possibly compound) value in the agent state.
-    /// #Arguments
+    /// # Arguments
     /// * `name` - The name of the store.
     /// * `kind` - The kind of the store.
     fn add_store(
@@ -270,7 +270,7 @@ pub type AgentInitResult = Result<AgentTask, AgentInitError>;
 pub trait Agent {
     /// Running an agent results in future that will perform the initialization of the agent and
     /// then yield another future that will actually run the agent.
-    /// #Arguments
+    /// # Arguments
     /// * `route` - The node URI of this agent instance.
     /// * `route_params` - Parameters extracted from the route URI.
     /// * `config` - Configuration parameters for the agent.

api/swimos_client_api/src/downlink/mod.rs

@@ -58,7 +58,7 @@ pub trait Downlink {
     /// Create a task that will manage the state of the downlink and service anything that is
     /// observing it/ pushing data to it.
     ///
-    /// #Arguments
+    /// # Arguments
     /// * `path` - The path to the lane to which the downlink should be attached.
     /// * `config` - Configuration parameters for the downlink task.
     /// * `input` - Byte channel on which updates will be received from the runtime.

api/swimos_form/src/lib.rs

@@ -20,7 +20,7 @@
 //! [`std::collections::HashMap`].
 //!
 //! A derivation macro is provided that can automatically generate implementations for straightforward
-//! struct and enum types. For instructions on how to use this, see the the [`Form`] trait or the SwimOS
+//! struct and enum types. For instructions on how to use this, see the [`Form`] trait or the SwimOS
 //! documentation.
 
 #![allow(clippy::match_wild_err_arm)]

api/swimos_form/src/structural/generic/coproduct.rs

@@ -45,7 +45,7 @@ impl Coproduct for CNil {
 }
 
 /// A non-empty coproduct. In general, we should have `T: Coproduct`, however, this makes it
-/// impossible to implement traits for general co-products due the the potentially unbounded
+/// impossible to implement traits for general co-products due potentially unbounded
 /// recursion.
 pub enum CCons<H, T> {
     Head(H),

api/swimos_form/src/structural/generic/header.rs

@@ -139,7 +139,7 @@ impl<T, S: AppendHeaders> HeaderWithBody<T, S> {
 }
 
 /// This trait allows all of the types in this crate to be used with a unified interface
-/// in the the macro-derived implementations.
+/// in the macro-derived implementations.
 pub trait AppendHeaders {
     /// The number of items that will be written into the attribute body.
     fn num_items(&self) -> usize;

api/swimos_form/src/structural/read/recognizer/mod.rs

@@ -262,7 +262,7 @@ pub struct NamedFieldsRecognizer<T, Flds> {
 impl<T, Flds> NamedFieldsRecognizer<T, Flds> {
     /// Configure a recognizer.
     ///
-    /// #Arguments
+    /// # Arguments
     ///
     /// * `fields` - The state for the state machine.
     /// * `select_index` - Map the field names of the type to integer indicies.
@@ -293,7 +293,7 @@ impl<T, Flds> NamedFieldsRecognizer<T, Flds> {
 
     /// Configure a recognizer for the type unpacked into an attribute body.
     ///
-    /// #Arguments
+    /// # Arguments
     ///
     /// * `fields` - The state for the state machine.
     /// * `select_index` - Map the field names of the type to integer indicies.
@@ -431,7 +431,7 @@ pub struct OrdinalFieldsRecognizer<T, Flds> {
 impl<T, Flds> OrdinalFieldsRecognizer<T, Flds> {
     /// Configure a recognizer.
     ///
-    /// #Arguments
+    /// # Arguments
     ///
     /// * `fields` - The state for the state machine.
     /// * `num_fields` - The total number of named fields in the representation.
@@ -459,7 +459,7 @@ impl<T, Flds> OrdinalFieldsRecognizer<T, Flds> {
 
     /// Configure a recognizer for the type unpacked into an attribute body.
     ///
-    /// #Arguments
+    /// # Arguments
     ///
     /// * `fields` - The state for the state machine.
     /// * `num_fields` - The total number of named fields in the representation.
@@ -804,7 +804,7 @@ impl<T, Flds> OrdinalVTable<T, Flds> {
 }
 
 impl<T, Flds> LabelledStructRecognizer<T, Flds> {
-    /// #Arguments
+    /// # Arguments
     /// * `tag` - The expected name of the first attribute or an inidcation that it should be used
     /// to populate a field.
     /// * `fields` - The state of the recognizer state machine (specified by the macro).
@@ -831,7 +831,7 @@ impl<T, Flds> LabelledStructRecognizer<T, Flds> {
     /// of the record has already been read before this recognizers is called so the initial state
     /// is skipped.
     ///
-    /// #Arguments
+    /// # Arguments
     /// * `fields` - The state of the recognizer state machine (specified by the macro).
     /// * `num_fields` - The total numer of (non-skipped) fields that the recognizer expects.
     /// * `vtable` - Functions that are generated by the macro that determine how incoming events
@@ -854,7 +854,7 @@ impl<T, Flds> LabelledStructRecognizer<T, Flds> {
 }
 
 impl<T, Flds> OrdinalStructRecognizer<T, Flds> {
-    /// #Arguments
+    /// # Arguments
     /// * `tag` - The expected name of the first attribute or an inidcation that it should be used
     /// to populate a field.
     /// * `fields` - The state of the recognizer state machine (specified by the macro).
@@ -881,7 +881,7 @@ impl<T, Flds> OrdinalStructRecognizer<T, Flds> {
     /// of the record has already been read before this recognizers is called so the initial state
     /// is skipped.
     ///
-    /// #Arguments
+    /// # Arguments
     /// * `fields` - The state of the recognizer state machine (specified by the macro).
     /// * `num_fields` - The total numer of (non-skipped) fields that the recognizer expects.
     /// * `vtable` - Functions that are generated by the macro that determine how incoming events
@@ -1453,7 +1453,7 @@ pub struct DelegateStructRecognizer<T, Flds> {
 }
 
 impl<T, Flds> DelegateStructRecognizer<T, Flds> {
-    /// #Arguments
+    /// # Arguments
     /// * `tag` - The expected name of the first attribute or an inidcation that it should be used
     /// to populate a field.
     /// * `fields` - The state of the recognizer state machine (specified by the macro).
@@ -1483,7 +1483,7 @@ impl<T, Flds> DelegateStructRecognizer<T, Flds> {
     /// of the record has already been read before this recognizers is called so the initial state
     /// is skipped.
     ///
-    /// #Arguments
+    /// # Arguments
     /// * `fields` - The state of the recognizer state machine (specified by the macro).
     /// * `num_fields` - The total numer of (non-skipped) fields that the recognizer expects.
     /// * `vtable` - Functions that are generated by the macro that determine how incoming events
@@ -1702,7 +1702,7 @@ pub struct TaggedEnumRecognizer<Var> {
 }
 
 impl<Var> TaggedEnumRecognizer<Var> {
-    /// #Arguments
+    /// # Arguments
     /// * `select_var` - A function that configures the wrapped recognizer to expect the
     /// representation of the appropriate variant, based on the name of the tag attribute.
     pub fn new(select_var: fn(&str) -> Option<Var>) -> Self {
@@ -1765,7 +1765,7 @@ pub struct UnitStructRecognizer<T> {
 }
 
 impl<T> UnitStructRecognizer<T> {
-    /// #Arguments
+    /// # Arguments
     /// * `tag` - The expected name of the tag attribute.
     /// * `on_done` - Factory to create an instance.
     pub fn new(tag: &'static str, on_done: fn() -> T) -> Self {
@@ -1777,7 +1777,7 @@ impl<T> UnitStructRecognizer<T> {
     }
 
     /// For an enum variant, the wrapping [`Recognizer`] will already have read the tag name.
-    /// #Arguments
+    /// # Arguments
     /// * `on_done` - Factory to create an instance.
     pub fn variant(on_done: fn() -> T) -> Self {
         UnitStructRecognizer {
@@ -1974,7 +1974,7 @@ pub struct HeaderRecognizer<T, Flds> {
 
 /// Create a recognizer for the body of the header attribute of a record.
 ///
-/// #Arguments
+/// # Arguments
 /// * `has_body` - Whether there is a field lifted to be the body of the header.
 /// * `make_fields` - Factory to construct the state of the recognizer.
 /// * `num_slots` - The number of slots lifted into the header.
@@ -1995,7 +1995,7 @@ where
     FirstOf::new(simple, flattened)
 }
 
-/// #Arguments
+/// # Arguments
 /// * `has_body` - Whehter there is a field lifted to be the body of the header.
 /// * `flattened` - Whether the record containing the fields has been flattened into the attribute
 /// body (and so does not have explicit record body delimiting).

api/swimos_form/src/structural/write/mod.rs

@@ -148,7 +148,7 @@ pub trait HeaderWriter: Sized {
     type Body: BodyWriter;
 
     /// Write an attribute into the header.
-    /// #Arguments
+    /// # Arguments
     /// * `name` - The name of the attribute.
     /// * `value` - The value whose structure will be used for the value of the attribute.
     fn write_attr<V: StructuralWritable>(
@@ -159,18 +159,18 @@ pub trait HeaderWriter: Sized {
 
     /// Delegate the remainder of the process to another value (its attributes will be appended
     /// to those already described).
-    /// #Arguments
+    /// # Arguments
     /// * `value` - The value whose structure will be used for the remainder of the process.
     fn delegate<V: StructuralWritable>(self, value: &V) -> Result<Self::Repr, Self::Error>;
 
     /// Delegate the remainder of the process to another value (its attributes will be appended
     /// to those already described), consuming it.
-    /// #Arguments
+    /// # Arguments
     /// * `value` - The value whose structure will be used for the remainder of the process.
     fn delegate_into<V: StructuralWritable>(self, value: V) -> Result<Self::Repr, Self::Error>;
 
     /// Write an attribute into the header, consuming the value.
-    /// #Arguments
+    /// # Arguments
     /// * `name` - The name of the attribute.
     /// * `value` - The value whose structure will be used for the value of the attribute.
     fn write_attr_into<L: Label, V: StructuralWritable>(
@@ -214,7 +214,7 @@ pub trait HeaderWriter: Sized {
     }
     /// Transform this writer into another which can be used to describe the items.
     ///
-    /// #Arguments
+    /// # Arguments
     /// * `kind` - Description of the contents of the body. If an incorrect value is provided,
     /// implementations may return an error but should not panic.
     /// * `num_items` - The number of items in the record. If an incorrect number is provided,

api/swimos_model/src/value.rs

@@ -191,7 +191,7 @@ impl Display for ValueKind {
 }
 
 impl Value {
-    /// Checks if the a [`Value`] is coercible into the [`ValueKind`] provided.
+    /// Checks if the [`Value`] is coercible into the [`ValueKind`] provided.
     pub fn is_coercible_to(&self, kind: ValueKind) -> bool {
         match &self {
             Value::Int32Value(n) => match &kind {