Merge pull request #114 from kinode-dao/hf/add-docs-links

add docs links

Author: nick1udwig

Cargo.lock

@@ -34,7 +34,7 @@ pub enum EthAction {
     },
 }
 
-/// Incoming `Request` containing subscription updates or errors that processes will receive.
+/// Incoming [`crate::Request`] containing subscription updates or errors that processes will receive.
 /// Can deserialize all incoming requests from eth:distro:sys to this type.
 ///
 /// Will be serialized and deserialized using `serde_json::to_vec` and `serde_json::from_slice`.
@@ -54,7 +54,7 @@ pub struct EthSubError {
     pub error: String,
 }
 
-/// The Response type which a process will get from requesting with an [`EthAction`] will be
+/// The [`crate::Response`] type which a process will get from requesting with an [`EthAction`] will be
 /// of this type, serialized and deserialized using `serde_json::to_vec`
 /// and `serde_json::from_slice`.
 ///
@@ -90,7 +90,7 @@ pub enum EthError {
 }
 
 /// The action type used for configuring eth:distro:sys. Only processes which have the "root"
-/// capability from eth:distro:sys can successfully send this action.
+/// [`crate::Capability`] from eth:distro:sys can successfully send this action.
 #[derive(Debug, Serialize, Deserialize)]
 pub enum EthConfigAction {
     /// Add a new provider to the list of providers.
@@ -126,12 +126,12 @@ pub enum EthConfigAction {
 pub enum EthConfigResponse {
     Ok,
     /// Response from a GetProviders request.
-    /// Note the [`crate::kernel_types::KnsUpdate`] will only have the correct `name` field.
+    /// Note the [`crate::net::KnsUpdate`] will only have the correct `name` field.
     /// The rest of the Update is not saved in this module.
     Providers(SavedConfigs),
     /// Response from a GetAccessSettings request.
     AccessSettings(AccessSettings),
-    /// Permission denied due to missing capability
+    /// Permission denied due to missing [`crate::Capability`]
     PermissionDenied,
     /// Response from a GetState request
     State {
@@ -194,11 +194,11 @@ impl Provider {
             request_timeout,
         }
     }
-    /// Sends a request based on the specified `EthAction` and parses the response.
+    /// Sends a request based on the specified [`EthAction`] and parses the response.
     ///
-    /// This function constructs a request targeting the Ethereum distribution system, serializes the provided `EthAction`,
+    /// This function constructs a request targeting the Ethereum distribution system, serializes the provided [`EthAction`],
     /// and sends it. It awaits a response with a specified timeout, then attempts to parse the response into the expected
-    /// type `T`. This method is generic and can be used for various Ethereum actions by specifying the appropriate `EthAction`
+    /// type `T`. This method is generic and can be used for various Ethereum actions by specifying the appropriate [`EthAction`]
     /// and return type `T`.
     pub fn send_request_and_parse_response<T: serde::de::DeserializeOwned>(
         &self,

src/eth.rs

@@ -1,7 +1,7 @@
 use crate::Request;
 
 /// Add a new icon and/or widget to the Kinode homepage. Note that the process calling this
-/// function must have the `homepage:homepage:sys` messaging capability.
+/// function must have the `homepage:homepage:sys` messaging [`crate::Capability`].
 ///
 /// This should be called upon process startup to ensure that the process is added to the homepage.
 ///
@@ -30,7 +30,7 @@ pub fn add_to_homepage(label: &str, icon: Option<&str>, path: Option<&str>, widg
 }
 
 /// Remove the caller process from the Kinode homepage. Note that the process calling this function
-/// must have the `homepage:homepage:sys` messaging capability.
+/// must have the `homepage:homepage:sys` messaging [`crate::Capability`].
 ///
 /// This usually isn't necessary as processes are not persisted on homepage between boots.
 pub fn remove_from_homepage() {

src/homepage.rs

@@ -6,11 +6,11 @@ use std::collections::HashMap;
 use std::str::FromStr;
 use thiserror::Error;
 
-/// Request type sent to the `http_client:distro:sys` service in order to open a
+/// [`crate::Request`] type sent to the `http_client:distro:sys` service in order to open a
 /// WebSocket connection, send a WebSocket message on an existing connection, or
 /// send an HTTP request.
 ///
-/// You will receive a Response with the format `Result<HttpClientResponse, HttpClientError>`.
+/// You will receive a [`crate::Response`] with the format `Result<HttpClientResponse, HttpClientError>`.
 ///
 /// Always serialized/deserialized as JSON.
 #[derive(Clone, Debug, Serialize, Deserialize)]
@@ -47,7 +47,7 @@ pub struct OutgoingHttpRequest {
     pub headers: HashMap<String, String>,
 }
 
-/// Request that comes from an open WebSocket client connection in the
+/// [`crate::Request`] that comes from an open WebSocket client connection in the
 /// `http_client:distro:sys` service. Be prepared to receive these after
 /// using a [`HttpClientAction::WebSocketOpen`] to open a connection.
 #[derive(Clone, Copy, Debug, Serialize, Deserialize)]
@@ -61,7 +61,7 @@ pub enum HttpClientRequest {
     },
 }
 
-/// Response type received from the `http_client:distro:sys` service after
+/// [`crate::Response`] type received from the `http_client:distro:sys` service after
 /// sending a successful [`HttpClientAction`] to it.
 #[derive(Debug, Serialize, Deserialize)]
 pub enum HttpClientResponse {
@@ -125,7 +125,7 @@ pub fn send_request(
 
 /// Make an HTTP request using http_client and await its response.
 ///
-/// Returns [`Response`] from the `http` crate if successful, with the body type as bytes.
+/// Returns HTTP response from the `http` crate if successful, with the body type as bytes.
 pub fn send_request_await_response(
     method: Method,
     url: url::Url,

src/http/client.rs

@@ -8,21 +8,21 @@ use serde::{Deserialize, Serialize};
 use std::collections::{HashMap, HashSet};
 use thiserror::Error;
 
-/// HTTP Request received from the `http_server:distro:sys` service as a
+/// [`crate::Request`] received from the `http_server:distro:sys` service as a
 /// result of either an HTTP or WebSocket binding, created via [`HttpServerAction`].
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub enum HttpServerRequest {
     Http(IncomingHttpRequest),
     /// Processes will receive this kind of request when a client connects to them.
-    /// If a process does not want this websocket open, they should issue a *request*
+    /// If a process does not want this websocket open, they should issue a [`crate::Request`]
     /// containing a [`HttpServerAction::WebSocketClose`] message and this channel ID.
     WebSocketOpen {
         path: String,
         channel_id: u32,
     },
-    /// Processes can both SEND and RECEIVE this kind of request
+    /// Processes can both SEND and RECEIVE this kind of [`crate::Request`]
     /// (send as [`HttpServerAction::WebSocketPush`]).
-    /// When received, will contain the message bytes as lazy_load_blob.
+    /// When received, will contain the message bytes as [`crate::LazyLoadBlob`].
     WebSocketPush {
         channel_id: u32,
         message_type: WsMessageType,
@@ -33,7 +33,7 @@ pub enum HttpServerRequest {
 }
 
 impl HttpServerRequest {
-    /// Parse a byte slice into an HttpServerRequest.
+    /// Parse a byte slice into an [`HttpServerRequest`].
     pub fn from_bytes(bytes: &[u8]) -> serde_json::Result<Self> {
         serde_json::from_slice(bytes)
     }
@@ -132,9 +132,9 @@ impl IncomingHttpRequest {
 
 /// The possible message types for [`HttpServerRequest::WebSocketPush`].
 /// Ping and Pong are limited to 125 bytes by the WebSockets protocol.
-/// Text will be sent as a Text frame, with the lazy_load_blob bytes
+/// Text will be sent as a Text frame, with the [`crate::LazyLoadBlob`] bytes
 /// being the UTF-8 encoding of the string. Binary will be sent as a
-/// Binary frame containing the unmodified lazy_load_blob bytes.
+/// Binary frame containing the unmodified [`crate::LazyLoadBlob`] bytes.
 #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
 pub enum WsMessageType {
     Text,
@@ -144,26 +144,26 @@ pub enum WsMessageType {
     Close,
 }
 
-/// Request type sent to `http_server:distro:sys` in order to configure it.
+/// [`crate::Request`] type sent to `http_server:distro:sys` in order to configure it.
 ///
-/// If a response is expected, all actions will return a Response
+/// If a [`crate::Response`] is expected, all actions will return a [`crate::Response`]
 /// with the shape `Result<(), HttpServerActionError>` serialized to JSON.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub enum HttpServerAction {
-    /// Bind expects a lazy_load_blob if and only if `cache` is TRUE. The lazy_load_blob should
-    /// be the static file to serve at this path.
+    /// Bind expects a [`crate::LazyLoadBlob`] if and only if `cache` is TRUE.
+    /// The [`crate::LazyLoadBlob`] should be the static file to serve at this path.
     Bind {
         path: String,
         /// Set whether the HTTP request needs a valid login cookie, AKA, whether
         /// the user needs to be logged in to access this path.
         authenticated: bool,
-        /// Set whether requests can be fielded from anywhere, or only the loopback address.
+        /// Set whether [`crate::Request`]s can be fielded from anywhere, or only the loopback address.
         local_only: bool,
-        /// Set whether to bind the lazy_load_blob statically to this path. That is, take the
-        /// lazy_load_blob bytes and serve them as the response to any request to this path.
+        /// Set whether to bind the [`crate::LazyLoadBlob`] statically to this path. That is, take the
+        /// [`crate::LazyLoadBlob`] bytes and serve them as the response to any request to this path.
         cache: bool,
     },
-    /// SecureBind expects a lazy_load_blob if and only if `cache` is TRUE. The lazy_load_blob should
+    /// SecureBind expects a [`crate::LazyLoadBlob`] if and only if `cache` is TRUE. The [`crate::LazyLoadBlob`] should
     /// be the static file to serve at this path.
     ///
     /// SecureBind is the same as Bind, except that it forces requests to be made from
@@ -174,8 +174,8 @@ pub enum HttpServerAction {
     /// will require the user to be logged in separately to the general domain authentication.
     SecureBind {
         path: String,
-        /// Set whether to bind the lazy_load_blob statically to this path. That is, take the
-        /// lazy_load_blob bytes and serve them as the response to any request to this path.
+        /// Set whether to bind the [`crate::LazyLoadBlob`] statically to this path. That is, take the
+        /// [`crate::LazyLoadBlob`] bytes and serve them as the response to any request to this path.
         cache: bool,
     },
     /// Unbind a previously-bound HTTP path
@@ -199,26 +199,26 @@ pub enum HttpServerAction {
     },
     /// Unbind a previously-bound WebSocket path
     WebSocketUnbind { path: String },
-    /// When sent, expects a lazy_load_blob containing the WebSocket message bytes to send.
+    /// When sent, expects a [`crate::LazyLoadBlob`] containing the WebSocket message bytes to send.
     WebSocketPush {
         channel_id: u32,
         message_type: WsMessageType,
     },
-    /// When sent, expects a `lazy_load_blob` containing the WebSocket message bytes to send.
-    /// Modifies the `lazy_load_blob` by placing into `WebSocketExtPushData` with id taken from
-    /// this `KernelMessage` and `kinode_message_type` set to `desired_reply_type`.
+    /// When sent, expects a [`crate::LazyLoadBlob`] containing the WebSocket message bytes to send.
+    /// Modifies the [`crate::LazyLoadBlob`] by placing into [`HttpServerAction::WebSocketExtPushData`]` with id taken from
+    /// this [`KernelMessage`]` and `kinode_message_type` set to `desired_reply_type`.
     WebSocketExtPushOutgoing {
         channel_id: u32,
         message_type: WsMessageType,
         desired_reply_type: MessageType,
     },
     /// For communicating with the ext.
-    /// Kinode's http_server sends this to the ext after receiving `WebSocketExtPushOutgoing`.
+    /// Kinode's http_server sends this to the ext after receiving [`HttpServerAction::WebSocketExtPushOutgoing`].
     /// Upon receiving reply with this type from ext, http_server parses, setting:
     /// * id as given,
-    /// * message type as given (Request or Response),
-    /// * body as HttpServerRequest::WebSocketPush,
-    /// * blob as given.
+    /// * message type as given ([`crate::Request`] or [`crate::Response`]),
+    /// * body as [`HttpServerRequest::WebSocketPush`],
+    /// * [`crate::LazyLoadBlob`] as given.
     WebSocketExtPushData {
         id: u64,
         kinode_message_type: MessageType,
@@ -230,11 +230,12 @@ pub enum HttpServerAction {
 
 /// HTTP Response type that can be shared over Wasm boundary to apps.
 /// Respond to [`IncomingHttpRequest`] with this type.
+///
+/// BODY is stored in the [`crate::LazyLoadBlob`] as bytes
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct HttpResponse {
     pub status: u16,
     pub headers: HashMap<String, String>,
-    // BODY is stored in the lazy_load_blob, as bytes
 }
 
 impl HttpResponse {
@@ -268,7 +269,7 @@ impl HttpResponse {
     }
 }
 
-/// Part of the Response type issued by http_server
+/// Part of the [`crate::Response`] type issued by http_server
 #[derive(Clone, Debug, Error, Serialize, Deserialize)]
 pub enum HttpServerError {
     #[error("request could not be parsed to HttpServerAction: {req}.")]
@@ -287,7 +288,7 @@ pub enum HttpServerError {
     UnexpectedResponse,
 }
 
-/// Whether the WebSocketPush is a request or a response.
+/// Whether the [`HttpServerAction::WebSocketPush`] is [`crate::Request`] or [`crate::Response`].
 #[derive(Clone, Copy, Debug, Serialize, Deserialize)]
 pub enum MessageType {
     Request,

src/http/server.rs

@@ -147,7 +147,7 @@ pub enum KernelCommand {
     /// The process that sends this command will be given messaging capabilities
     /// for the new process if `public` is false.
     ///
-    /// All capabilities passed into initial_capabilities must be held by the source
+    /// All capabilities passed into `initial_capabilities` must be held by the source
     /// of this message, or the kernel will discard them (silently for now).
     InitializeProcess {
         id: ProcessId,
@@ -273,7 +273,7 @@ impl StateError {
 /// - `image`: An optional field containing a URL to an image representing the package.
 /// - `external_url`: An optional field containing a URL for more information about the package. For example, a link to the github repository.
 /// - `animation_url`: An optional field containing a URL to an animation or video representing the package.
-/// - `properties`: A requried field containing important information about the package.
+/// - `properties`: A required field containing important information about the package.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct Erc721Metadata {
     pub name: Option<String>,
@@ -288,15 +288,15 @@ pub struct Erc721Metadata {
 /// This follows the [ERC1155](https://github.com/ethereum/ercs/blob/master/ERCS/erc-1155.md#erc-1155-metadata-uri-json-schema) metadata standard.
 ///
 /// Fields:
-/// - `package_name`: The unique name of the package, used in the `PackageId`, e.g. `package_name:publisher`.
-/// - `publisher`: The KNS identity of the package publisher used in the `PackageId`, e.g. `package_name:publisher`
+/// - `package_name`: The unique name of the package, used in the [`crate::PackageId`], e.g. `package_name:publisher`.
+/// - `publisher`: The KNS identity of the package publisher used in the [`crate::PackageId`], e.g. `package_name:publisher`
 /// - `current_version`: A string representing the current version of the package, e.g. `1.0.0`.
 /// - `mirrors`: A list of NodeIds where the package can be found, providing redundancy.
 /// - `code_hashes`: A map from version names to their respective SHA-256 hashes.
 /// - `license`: An optional field containing the license of the package.
 /// - `screenshots`: An optional field containing a list of URLs to screenshots of the package.
 /// - `wit_version`: An optional field containing the version of the WIT standard that the package adheres to.
-/// - `dependencies`: An optional field containing a list of `PackageId`s: API dependencies.
+/// - `dependencies`: An optional field containing a list of [`crate::PackageId`]s: API dependencies.
 /// - `api_includes`: An optional field containing a list of `PathBuf`s: additional files to include in the `api.zip`.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct Erc721Properties {

src/kernel_types.rs

@@ -246,7 +246,7 @@ pub struct Fact {
 }
 
 /// Errors that can occur when decoding a log from the kimap using
-/// [`decode_mint_log`] or [`decode_note_log`].
+/// [`decode_mint_log()`] or [`decode_note_log()`].
 #[derive(Clone, Debug, Deserialize, Serialize)]
 pub enum DecodeLogError {
     /// The log's topic is not a mint or note event.
@@ -323,7 +323,7 @@ pub fn namehash(name: &str) -> String {
 
 /// Decode a mint log from the kimap into a 'resolved' format.
 ///
-/// Uses `valid_name` to check if the name is valid.
+/// Uses [`valid_name()`] to check if the name is valid.
 pub fn decode_mint_log(log: &crate::eth::Log) -> Result<Mint, DecodeLogError> {
     let contract::Note::SIGNATURE_HASH = log.topics()[0] else {
         return Err(DecodeLogError::UnexpectedTopic(log.topics()[0]));
@@ -342,7 +342,7 @@ pub fn decode_mint_log(log: &crate::eth::Log) -> Result<Mint, DecodeLogError> {
 
 /// Decode a note log from the kimap into a 'resolved' format.
 ///
-/// Uses `valid_name` to check if the name is valid.
+/// Uses [`valid_name()`] to check if the name is valid.
 pub fn decode_note_log(log: &crate::eth::Log) -> Result<Note, DecodeLogError> {
     let contract::Note::SIGNATURE_HASH = log.topics()[0] else {
         return Err(DecodeLogError::UnexpectedTopic(log.topics()[0]));
@@ -393,7 +393,7 @@ pub fn resolve_parent(log: &crate::eth::Log, timeout: Option<u64>) -> Option<Str
 /// Given a [`crate::eth::Log`] (which must be a log from kimap), resolve the full name
 /// of the new entry or note.
 ///
-/// Uses `valid_name` to check if the name is valid.
+/// Uses [`valid_name()`] to check if the name is valid.
 pub fn resolve_full_name(log: &crate::eth::Log, timeout: Option<u64>) -> Option<String> {
     let parent_hash = log.topics()[1].to_string();
     let parent_name = net::get_name(&parent_hash, log.block_number, timeout)?;

src/kimap.rs

@@ -3,9 +3,9 @@ use serde::{de::DeserializeOwned, Deserialize, Serialize};
 use std::marker::PhantomData;
 use thiserror::Error;
 
-/// Actions are sent to a specific key value database, "db" is the name,
-/// "package_id" is the package. Capabilities are checked, you can access another process's
-/// database if it has given you the capability.
+/// Actions are sent to a specific key value database, `db` is the name,
+/// `package_id` is the [`PackageId`]. Capabilities are checked, you can access another process's
+/// database if it has given you the [`crate::Capability`].
 #[derive(Debug, Serialize, Deserialize)]
 pub struct KvRequest {
     pub package_id: PackageId,
@@ -52,7 +52,7 @@ pub enum KvError {
 }
 
 /// Kv helper struct for a db.
-/// Opening or creating a kv will give you a Result<Kv>.
+/// Opening or creating a kv will give you a `Result<Kv>`.
 /// You can call it's impl functions to interact with it.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Kv<K, V> {