From d9848a08b24b36487b1c63264a8eeb10730568d0 Mon Sep 17 00:00:00 2001
From: wojciechkepka <wojtek.kepka@protonmail.com>
Date: Thu, 11 Mar 2021 18:56:16 +0100
Subject: Add Docker API reference hyperlinks to doc comments

---
 src/container.rs | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 src/exec.rs      | 12 ++++++++++++
 src/image.rs     | 24 ++++++++++++++++++++++++
 src/network.rs   | 14 ++++++++++++++
 src/service.rs   | 14 ++++++++++++++
 src/volume.rs    | 11 +++++++++++
 6 files changed, 123 insertions(+)

(limited to 'src')

diff --git a/src/container.rs b/src/container.rs
index dad0dc9..24c41d6 100644
--- a/src/container.rs
+++ b/src/container.rs
@@ -31,6 +31,8 @@ use crate::datetime::datetime_from_unix_timestamp;
 use chrono::{DateTime, Utc};
 
 /// Interface for accessing and manipulating a docker container
+///
+/// Api Reference: <https://docs.docker.com/engine/api/v1.41/#tag/Container>
 pub struct Container<'docker> {
     docker: &'docker Docker,
     id: String,
@@ -57,6 +59,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Inspects the current docker container instance's details
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerInspect>
     pub async fn inspect(&self) -> Result<ContainerDetails> {
         self.docker
             .get_json::<ContainerDetails>(&format!("/containers/{}/json", self.id)[..])
@@ -64,6 +68,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Returns a `top` view of information about the container process
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerTop>
     pub async fn top(
         &self,
         psargs: Option<&str>,
@@ -79,6 +85,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Returns a stream of logs emitted but the container instance
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerLogs>
     pub fn logs(
         &self,
         opts: &LogsOptions,
@@ -111,6 +119,8 @@ impl<'docker> Container<'docker> {
     /// The `[TtyMultiplexer]` implements Stream for returning Stdout and Stderr chunks. It also implements `[AsyncWrite]` for writing to Stdin.
     ///
     /// The multiplexer can be split into its read and write halves with the `[split](TtyMultiplexer::split)` method
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerAttach>
     pub async fn attach(&self) -> Result<TtyMultiPlexer<'docker>> {
         let tcp_stream = self.attach_raw().await?;
 
@@ -118,6 +128,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Returns a set of changes made to the container instance
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerChanges>
     pub async fn changes(&self) -> Result<Vec<Change>> {
         self.docker
             .get_json::<Vec<Change>>(&format!("/containers/{}/changes", self.id)[..])
@@ -125,6 +137,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Exports the current docker container into a tarball
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerExport>
     pub fn export(&self) -> impl Stream<Item = Result<Vec<u8>>> + 'docker {
         self.docker
             .stream_get(format!("/containers/{}/export", self.id))
@@ -132,6 +146,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Returns a stream of stats specific to this container instance
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerStats>
     pub fn stats(&self) -> impl Stream<Item = Result<Stats>> + Unpin + 'docker {
         let codec = futures_codec::LinesCodec {};
 
@@ -152,6 +168,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Start the container instance
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerStart>
     pub async fn start(&self) -> Result<()> {
         self.docker
             .post(&format!("/containers/{}/start", self.id)[..], None)
@@ -160,6 +178,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Stop the container instance
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerStop>
     pub async fn stop(
         &self,
         wait: Option<Duration>,
@@ -177,6 +197,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Restart the container instance
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerRestart>
     pub async fn restart(
         &self,
         wait: Option<Duration>,
@@ -193,6 +215,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Kill the container instance
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerKill>
     pub async fn kill(
         &self,
         signal: Option<&str>,
@@ -209,6 +233,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Rename the container instance
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerRename>
     pub async fn rename(
         &self,
         name: &str,
@@ -226,6 +252,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Pause the container instance
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerPause>
     pub async fn pause(&self) -> Result<()> {
         self.docker
             .post(&format!("/containers/{}/pause", self.id)[..], None)
@@ -234,6 +262,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Unpause the container instance
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerUnpause>
     pub async fn unpause(&self) -> Result<()> {
         self.docker
             .post(&format!("/containers/{}/unpause", self.id)[..], None)
@@ -242,6 +272,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Wait until the container stops
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerWait>
     pub async fn wait(&self) -> Result<Exit> {
         self.docker
             .post_json(format!("/containers/{}/wait", self.id), Payload::None)
@@ -251,6 +283,8 @@ impl<'docker> Container<'docker> {
     /// Delete the container instance
     ///
     /// Use remove instead to use the force/v options.
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerDelete>
     pub async fn delete(&self) -> Result<()> {
         self.docker
             .delete(&format!("/containers/{}", self.id)[..])
@@ -259,6 +293,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Delete the container instance (todo: force/v)
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerRemove>
     pub async fn remove(
         &self,
         opts: RmContainerOptions,
@@ -272,6 +308,8 @@ impl<'docker> Container<'docker> {
     }
 
     /// Execute a command in this container
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#tag/Exec>
     pub fn exec(
         &self,
         opts: &ExecContainerOptions,
@@ -287,6 +325,8 @@ impl<'docker> Container<'docker> {
     /// directory, `path` should end in `/` or `/`. (assuming a path separator of `/`). If `path`
     /// ends in `/.`  then this indicates that only the contents of the path directory should be
     /// copied.  A symlink is always resolved to its target.
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerArchive>
     pub fn copy_from(
         &self,
         path: &Path,
@@ -303,6 +343,8 @@ impl<'docker> Container<'docker> {
     ///
     /// The file will be copied at the given location (see `path`) and will be owned by root
     /// with access mask 644.
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/PutContainerArchive>
     pub async fn copy_file_into<P: AsRef<Path>>(
         &self,
         path: P,
@@ -332,6 +374,8 @@ impl<'docker> Container<'docker> {
     /// Copy a tarball (see `body`) to the container.
     ///
     /// The tarball will be copied to the container and extracted at the given location (see `path`).
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/PutContainerArchive>
     pub async fn copy_to(
         &self,
         path: &Path,
@@ -354,6 +398,8 @@ impl<'docker> Container<'docker> {
 }
 
 /// Interface for docker containers
+///
+/// Api Reference: <https://docs.docker.com/engine/api/v1.41/#tag/Containers>
 pub struct Containers<'docker> {
     docker: &'docker Docker,
 }
@@ -365,6 +411,8 @@ impl<'docker> Containers<'docker> {
     }
 
     /// Lists the container instances on the docker host
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerList>
     pub async fn list(
         &self,
         opts: &ContainerListOptions,
diff --git a/src/exec.rs b/src/exec.rs
index f90a08a..2f512a9 100644
--- a/src/exec.rs
+++ b/src/exec.rs
@@ -19,6 +19,8 @@ use crate::{
 };
 
 /// Interface for docker exec instance
+///
+/// Api Reference: <https://docs.docker.com/engine/api/v1.41/#tag/Exec>
 pub struct Exec<'docker> {
     docker: &'docker Docker,
     id: String,
@@ -39,6 +41,8 @@ impl<'docker> Exec<'docker> {
     }
 
     /// Creates a new exec instance that will be executed in a container with id == container_id
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ContainerExec>
     pub async fn create(
         docker: &'docker Docker,
         container_id: &str,
@@ -132,6 +136,8 @@ impl<'docker> Exec<'docker> {
     }
 
     /// Starts this exec instance returning a multiplexed tty stream
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ExecStart>
     pub fn start(&self) -> impl Stream<Item = Result<tty::TtyChunk>> + 'docker {
         // We must take ownership of the docker reference to not needlessly tie the stream to the
         // lifetime of `self`.
@@ -154,12 +160,18 @@ impl<'docker> Exec<'docker> {
     }
 
     /// Inspect this exec instance to aquire detailed information
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ExecInpsect>
     pub async fn inspect(&self) -> Result<ExecDetails> {
         self.docker
             .get_json(&format!("/exec/{}/json", &self.id)[..])
             .await
     }
 
+    /// Resize the TTY session used by an exec instance. This only works if the exec was created
+    /// with `tty` enabled.
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ExecResize>
     pub async fn resize(
         &self,
         opts: &ExecResizeOptions,
diff --git a/src/image.rs b/src/image.rs
index 45b24af..e69f85a 100644
--- a/src/image.rs
+++ b/src/image.rs
@@ -18,6 +18,8 @@ use crate::datetime::datetime_from_unix_timestamp;
 use chrono::{DateTime, Utc};
 
 /// Interface for accessing and manipulating a named docker image
+///
+/// Api Reference: <https://docs.docker.com/engine/api/v1.41/#tag/Image>
 pub struct Image<'docker> {
     docker: &'docker Docker,
     name: String,
@@ -39,6 +41,8 @@ impl<'docker> Image<'docker> {
     }
 
     /// Inspects a named image's details
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ImageInspect>
     pub async fn inspect(&self) -> Result<ImageDetails> {
         self.docker
             .get_json(&format!("/images/{}/json", self.name)[..])
@@ -46,6 +50,8 @@ impl<'docker> Image<'docker> {
     }
 
     /// Lists the history of the images set of changes
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ImageHistory>
     pub async fn history(&self) -> Result<Vec<History>> {
         self.docker
             .get_json(&format!("/images/{}/history", self.name)[..])
@@ -53,6 +59,8 @@ impl<'docker> Image<'docker> {
     }
 
     /// Deletes an image
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ImagePrune>
     pub async fn delete(&self) -> Result<Vec<Status>> {
         self.docker
             .delete_json::<Vec<Status>>(&format!("/images/{}", self.name)[..])
@@ -60,6 +68,8 @@ impl<'docker> Image<'docker> {
     }
 
     /// Export this image to a tarball
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ImageGet>
     pub fn export(&self) -> impl Stream<Item = Result<Vec<u8>>> + Unpin + 'docker {
         Box::pin(
             self.docker
@@ -69,6 +79,8 @@ impl<'docker> Image<'docker> {
     }
 
     /// Adds a tag to an image
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ImageTag>
     pub async fn tag(
         &self,
         opts: &TagOptions,
@@ -94,6 +106,8 @@ impl<'docker> Images<'docker> {
     }
 
     /// Builds a new image build by reading a Dockerfile in a target directory
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ImageBuild>
     pub fn build(
         &self,
         opts: &BuildOptions,
@@ -130,6 +144,8 @@ impl<'docker> Images<'docker> {
     }
 
     /// Lists the docker images on the current docker host
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ImageList>
     pub async fn list(
         &self,
         opts: &ImageListOptions,
@@ -155,6 +171,8 @@ impl<'docker> Images<'docker> {
     }
 
     /// Search for docker images by term
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ImageSearch>
     pub async fn search(
         &self,
         term: &str,
@@ -168,6 +186,8 @@ impl<'docker> Images<'docker> {
     }
 
     /// Pull and create a new docker images from an existing image
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ImagePull>
     pub fn pull(
         &self,
         opts: &PullOptions,
@@ -188,6 +208,8 @@ impl<'docker> Images<'docker> {
 
     /// exports a collection of named images,
     /// either by name, name:tag, or image id, into a tarball
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ImageGetAll>
     pub fn export(
         &self,
         names: Vec<&str>,
@@ -203,6 +225,8 @@ impl<'docker> Images<'docker> {
 
     /// imports an image or set of images from a given tarball source
     /// source can be uncompressed on compressed via gzip, bzip2 or xz
+    ///
+    /// Api Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ImageLoad>
     pub fn import<R>(
         self,
         mut tarball: R,
diff --git a/src/network.rs b/src/network.rs
index e274d2d..5c5535d 100644
--- a/src/network.rs
+++ b/src/network.rs
@@ -18,6 +18,8 @@ use crate::{
 };
 
 /// Interface for docker network
+///
+/// API Reference: <https://docs.docker.com/engine/api/v1.41/#tag/Network>
 pub struct Networks<'docker> {
     docker: &'docker Docker,
 }
@@ -29,6 +31,8 @@ impl<'docker> Networks<'docker> {
     }
 
     /// List the docker networks on the current docker host
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/NetworkList>
     pub async fn list(
         &self,
         opts: &NetworkListOptions,
@@ -52,6 +56,8 @@ impl<'docker> Networks<'docker> {
     }
 
     /// Create a new Network instance
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/NetworkCreate>
     pub async fn create(
         &self,
         opts: &NetworkCreateOptions,
@@ -92,6 +98,8 @@ impl<'docker> Network<'docker> {
     }
 
     /// Inspects the current docker network instance's details
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/NetworkInspect>
     pub async fn inspect(&self) -> Result<NetworkInfo> {
         self.docker
             .get_json(&format!("/networks/{}", self.id)[..])
@@ -99,6 +107,8 @@ impl<'docker> Network<'docker> {
     }
 
     /// Delete the network instance
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/NetworkDelete>
     pub async fn delete(&self) -> Result<()> {
         self.docker
             .delete(&format!("/networks/{}", self.id)[..])
@@ -107,6 +117,8 @@ impl<'docker> Network<'docker> {
     }
 
     /// Connect container to network
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/NetworkConnect>
     pub async fn connect(
         &self,
         opts: &ContainerConnectionOptions,
@@ -115,6 +127,8 @@ impl<'docker> Network<'docker> {
     }
 
     /// Disconnect container to network
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/NetworkDisconnect>
     pub async fn disconnect(
         &self,
         opts: &ContainerConnectionOptions,
diff --git a/src/service.rs b/src/service.rs
index 8a2796b..9c25522 100644
--- a/src/service.rs
+++ b/src/service.rs
@@ -22,6 +22,8 @@ use crate::{
 use chrono::{DateTime, Utc};
 
 /// Interface for docker services
+///
+/// API Reference: <https://docs.docker.com/engine/api/v1.41/#tag/Service>
 pub struct Services<'docker> {
     docker: &'docker Docker,
 }
@@ -33,6 +35,8 @@ impl<'docker> Services<'docker> {
     }
 
     /// Lists the docker services on the current docker host
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ServiceList>
     pub async fn list(
         &self,
         opts: &ServiceListOptions,
@@ -56,6 +60,8 @@ impl<'docker> Services<'docker> {
 }
 
 /// Interface for accessing and manipulating a named docker volume
+///
+/// API Reference: <https://docs.docker.com/engine/api/v1.41/#tag/Service>
 pub struct Service<'docker> {
     docker: &'docker Docker,
     name: String,
@@ -77,6 +83,8 @@ impl<'docker> Service<'docker> {
     }
 
     /// Creates a new service from ServiceOptions
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ServiceCreate>
     pub async fn create(
         &self,
         opts: &ServiceOptions,
@@ -98,6 +106,8 @@ impl<'docker> Service<'docker> {
     }
 
     /// Inspects a named service's details
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ServiceInspect>
     pub async fn inspect(&self) -> Result<ServiceDetails> {
         self.docker
             .get_json(&format!("/services/{}", self.name)[..])
@@ -105,6 +115,8 @@ impl<'docker> Service<'docker> {
     }
 
     /// Deletes a service
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ServiceDelete>
     pub async fn delete(&self) -> Result<()> {
         self.docker
             .delete_json(&format!("/services/{}", self.name)[..])
@@ -112,6 +124,8 @@ impl<'docker> Service<'docker> {
     }
 
     /// Returns a stream of logs from a service
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/ServiceLogs>
     pub fn logs(
         &self,
         opts: &LogsOptions,
diff --git a/src/volume.rs b/src/volume.rs
index cbd4d91..50f0f7a 100644
--- a/src/volume.rs
+++ b/src/volume.rs
@@ -20,6 +20,8 @@ use crate::{
 use chrono::{DateTime, Utc};
 
 /// Interface for docker volumes
+///
+/// API Reference: <https://docs.docker.com/engine/api/v1.41/#tag/Volume>
 pub struct Volumes<'docker> {
     docker: &'docker Docker,
 }
@@ -30,6 +32,9 @@ impl<'docker> Volumes<'docker> {
         Volumes { docker }
     }
 
+    /// Creates a new docker volume.
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/VolumeCreate>
     pub async fn create(
         &self,
         opts: &VolumeCreateOptions,
@@ -43,6 +48,8 @@ impl<'docker> Volumes<'docker> {
     }
 
     /// Lists the docker volumes on the current docker host
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/VolumeList>
     pub async fn list(&self) -> Result<Vec<VolumeInfo>> {
         let path = vec!["/volumes".to_owned()];
 
@@ -63,6 +70,8 @@ impl<'docker> Volumes<'docker> {
 }
 
 /// Interface for accessing and manipulating a named docker volume
+///
+/// API Reference: <https://docs.docker.com/engine/api/v1.41/#tag/Volume>
 pub struct Volume<'docker> {
     docker: &'docker Docker,
     name: String,
@@ -84,6 +93,8 @@ impl<'docker> Volume<'docker> {
     }
 
     /// Deletes a volume
+    ///
+    /// API Reference: <https://docs.docker.com/engine/api/v1.41/#operation/VolumeDelete>
     pub async fn delete(&self) -> Result<()> {
         self.docker
             .delete(&format!("/volumes/{}", self.name)[..])
-- 
cgit v1.2.3