From c3806bac008420db0366b2cb0112f04f47d6f2b5 Mon Sep 17 00:00:00 2001
From: kjuulh <contact@kjuulh.io>
Date: Sun, 19 Feb 2023 22:38:36 +0100
Subject: [PATCH] feat(sdk): add documentation strings

---
 crates/dagger-codegen/src/rust/functions.rs   |  81 +++-
 .../src/rust/templates/object_tmpl.rs         |   3 +-
 crates/dagger-sdk/src/gen.rs                  | 421 ++++++++++++++++++
 3 files changed, 499 insertions(+), 6 deletions(-)

diff --git a/crates/dagger-codegen/src/rust/functions.rs b/crates/dagger-codegen/src/rust/functions.rs
index 492210e..7cee7c7 100644
--- a/crates/dagger-codegen/src/rust/functions.rs
+++ b/crates/dagger-codegen/src/rust/functions.rs
@@ -64,9 +64,11 @@ pub fn format_function(funcs: &CommonFunctions, field: &FullTypeFields) -> Optio
         .pipe(|t| &t.type_ref)
         .pipe(|t| render_output_type(funcs, t));
 
-    if let Some((args, true)) = args {
+    if let Some((args, desc, true)) = args {
         let required_args = format_required_function_args(funcs, field);
         Some(quote! {
+            $(field.description.pipe(|d| format_struct_comment(d)))
+            $(&desc)
             $(&signature)(
                 $(required_args)
             ) -> $(output_type.as_ref()) {
@@ -77,6 +79,8 @@ pub fn format_function(funcs: &CommonFunctions, field: &FullTypeFields) -> Optio
                 $(render_execution(funcs, field))
             }
 
+            $(field.description.pipe(|d| format_struct_comment(d)))
+            $(&desc)
             $(&signature)_opts$(lifecycle)(
                 $args
             ) -> $(output_type) {
@@ -90,8 +94,10 @@ pub fn format_function(funcs: &CommonFunctions, field: &FullTypeFields) -> Optio
         })
     } else {
         Some(quote! {
+            $(field.description.pipe(|d| format_struct_comment(d)))
+            $(if let Some((_, desc, _)) = &args => $desc)
             $(signature)(
-                $(if let Some((args, _)) = args => $args)
+                $(if let Some((args, _, _)) = &args => $args)
             ) -> $(output_type) {
                 let mut query = self.selection.select($(quoted(field.name.as_ref())));
 
@@ -268,7 +274,8 @@ fn format_function_args(
     funcs: &CommonFunctions,
     field: &FullTypeFields,
     lifecycle: Option<&rust::Tokens>,
-) -> Option<(rust::Tokens, bool)> {
+) -> Option<(rust::Tokens, rust::Tokens, bool)> {
+    let mut argument_description = Vec::new();
     if let Some(args) = field.args.as_ref() {
         let args = args
             .into_iter()
@@ -281,6 +288,18 @@ fn format_function_args(
                     let t = funcs.format_input_type(&s.input_value.type_);
                     let n = format_struct_name(&s.input_value.name);
 
+                    if let Some(desc) = s.input_value.description.as_ref().and_then(|d| {
+                        if d != "" {
+                            Some(write_comment_line(&format!("* `{n}` - {}", d)))
+                        } else {
+                            None
+                        }
+                    }) {
+                        argument_description.push(quote! {
+                            $(desc)
+                        });
+                    }
+
                     Some(quote! {
                         $(n): $(t),
                     })
@@ -294,15 +313,34 @@ fn format_function_args(
         };
 
         if type_field_has_optional(field) {
+            let field_name = field_options_struct_name(field);
+            argument_description.push(quote! {
+                $(field_name.pipe(|_| write_comment_line(&format!("* `opt` - optional argument, see inner type for documentation, use <func>_opts to use"))))
+            });
+
+            let description = quote! {
+                $(if argument_description.len() > 0 => $(format!("/// ")))
+                $(if argument_description.len() > 0 => $(format!("/// # Arguments")))
+                $(if argument_description.len() > 0 => $(format!("/// ")))
+                $(for arg_desc in argument_description join ($['\r']) => $arg_desc)
+            };
+
             Some((
                 quote! {
                     $(required_args)
-                    opts: $(field_options_struct_name(field))$(lifecycle)
+                    opts: $(field_name)$(lifecycle)
                 },
+                description,
                 true,
             ))
         } else {
-            Some((required_args, false))
+            let description = quote! {
+                $(if argument_description.len() > 0 => $(format!("/// ")))
+                $(if argument_description.len() > 0 => $(format!("/// # Arguments")))
+                $(if argument_description.len() > 0 => $(format!("/// ")))
+                $(for arg_desc in argument_description join ($['\r']) => $arg_desc)
+            };
+            Some((required_args, description, false))
         }
     } else {
         None
@@ -358,3 +396,36 @@ pub fn format_optional_args(
         .pipe(|t| render_optional_field_args(funcs, t))
         .flatten()
 }
+
+pub fn write_comment_line(content: &str) -> Option<rust::Tokens> {
+    let cnt = content.trim();
+    if cnt == "" {
+        return None;
+    }
+
+    let mut tokens = rust::Tokens::new();
+
+    for line in content.split('\n') {
+        tokens.append(format!("/// {}", line.trim()));
+        tokens.push();
+    }
+
+    Some(tokens)
+}
+
+pub fn format_struct_comment(desc: &str) -> Option<rust::Tokens> {
+    let lines = desc.trim().split("\n");
+
+    let formatted_lines = lines
+        .into_iter()
+        .map(write_comment_line)
+        .collect::<Vec<_>>();
+
+    if formatted_lines.len() > 0 {
+        Some(quote! {
+            $(for line in formatted_lines join($['\r']) => $line)
+        })
+    } else {
+        None
+    }
+}
diff --git a/crates/dagger-codegen/src/rust/templates/object_tmpl.rs b/crates/dagger-codegen/src/rust/templates/object_tmpl.rs
index dc09a3a..c9a998d 100644
--- a/crates/dagger-codegen/src/rust/templates/object_tmpl.rs
+++ b/crates/dagger-codegen/src/rust/templates/object_tmpl.rs
@@ -6,7 +6,7 @@ use itertools::Itertools;
 use crate::functions::{type_ref_is_optional, CommonFunctions};
 use crate::rust::functions::{
     field_options_struct_name, format_function, format_name, format_optional_args,
-    format_struct_name,
+    format_struct_comment, format_struct_name,
 };
 use crate::utility::OptionExt;
 
@@ -85,6 +85,7 @@ pub fn render_optional_field_args(
             contains_lifetime = true;
         }
         quote! {
+            $(a.description.pipe(|d| format_struct_comment(d)))
             #[builder(setter(into, strip_option))]
             pub $(format_struct_name(&a.name)): Option<$(type_)>,
         }
diff --git a/crates/dagger-sdk/src/gen.rs b/crates/dagger-sdk/src/gen.rs
index 92b0fc8..4c76fff 100644
--- a/crates/dagger-sdk/src/gen.rs
+++ b/crates/dagger-sdk/src/gen.rs
@@ -49,30 +49,43 @@ pub struct Container {
 #[derive(Builder, Debug, PartialEq)]
 pub struct ContainerBuildOpts<'a> {
 
+    /// Path to the Dockerfile to use.
+    /// Defaults to './Dockerfile'.
     #[builder(setter(into, strip_option))]
     pub dockerfile: Option<&'a str>,
+    /// Additional build arguments.
     #[builder(setter(into, strip_option))]
     pub build_args: Option<Vec<BuildArg>>,
+    /// Target build stage to build.
     #[builder(setter(into, strip_option))]
     pub target: Option<&'a str>,
 }
 #[derive(Builder, Debug, PartialEq)]
 pub struct ContainerExecOpts<'a> {
 
+    /// Command to run instead of the container's default command.
     #[builder(setter(into, strip_option))]
     pub args: Option<Vec<&'a str>>,
+    /// Content to write to the command's standard input before closing.
     #[builder(setter(into, strip_option))]
     pub stdin: Option<&'a str>,
+    /// Redirect the command's standard output to a file in the container.
     #[builder(setter(into, strip_option))]
     pub redirect_stdout: Option<&'a str>,
+    /// Redirect the command's standard error to a file in the container.
     #[builder(setter(into, strip_option))]
     pub redirect_stderr: Option<&'a str>,
+    /// Provide dagger access to the executed command.
+    /// Do not use this option unless you trust the command being executed.
+    /// The command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
     #[builder(setter(into, strip_option))]
     pub experimental_privileged_nesting: Option<bool>,
 }
 #[derive(Builder, Debug, PartialEq)]
 pub struct ContainerExportOpts {
 
+    /// Identifiers for other platform specific containers.
+    /// Used for multi-platform image.
     #[builder(setter(into, strip_option))]
     pub platform_variants: Option<Vec<ContainerId>>,
 }
@@ -85,6 +98,8 @@ pub struct ContainerPipelineOpts<'a> {
 #[derive(Builder, Debug, PartialEq)]
 pub struct ContainerPublishOpts {
 
+    /// Identifiers for other platform specific containers.
+    /// Used for multi-platform image.
     #[builder(setter(into, strip_option))]
     pub platform_variants: Option<Vec<ContainerId>>,
 }
@@ -105,12 +120,18 @@ pub struct ContainerWithDirectoryOpts<'a> {
 #[derive(Builder, Debug, PartialEq)]
 pub struct ContainerWithExecOpts<'a> {
 
+    /// Content to write to the command's standard input before closing.
     #[builder(setter(into, strip_option))]
     pub stdin: Option<&'a str>,
+    /// Redirect the command's standard output to a file in the container.
     #[builder(setter(into, strip_option))]
     pub redirect_stdout: Option<&'a str>,
+    /// Redirect the command's standard error to a file in the container.
     #[builder(setter(into, strip_option))]
     pub redirect_stderr: Option<&'a str>,
+    /// Provide dagger access to the executed command.
+    /// Do not use this option unless you trust the command being executed.
+    /// The command being executed WILL BE GRANTED FULL ACCESS TO YOUR HOST FILESYSTEM.
     #[builder(setter(into, strip_option))]
     pub experimental_privileged_nesting: Option<bool>,
 }
@@ -123,8 +144,10 @@ pub struct ContainerWithFileOpts {
 #[derive(Builder, Debug, PartialEq)]
 pub struct ContainerWithMountedCacheOpts {
 
+    /// Directory to use as the cache volume's root.
     #[builder(setter(into, strip_option))]
     pub source: Option<DirectoryId>,
+    /// Sharing mode of the cache volume.
     #[builder(setter(into, strip_option))]
     pub sharing: Option<CacheSharingMode>,
 }
@@ -138,6 +161,12 @@ pub struct ContainerWithNewFileOpts<'a> {
 }
 
 impl Container {
+    /// Initializes this container from a Dockerfile build, using the context, a dockerfile file path and some additional buildArgs.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `context` - Directory context used by the Dockerfile.
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn build(
         &self,
         context: DirectoryId,
@@ -153,6 +182,12 @@ impl Container {
         }
     }
 
+    /// Initializes this container from a Dockerfile build, using the context, a dockerfile file path and some additional buildArgs.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `context` - Directory context used by the Dockerfile.
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn build_opts<'a>(
         &self,
         context: DirectoryId,
@@ -177,6 +212,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves default arguments for future commands.
     pub async fn default_args(
         &self,
     ) -> eyre::Result<Vec<String>> {
@@ -184,6 +220,7 @@ impl Container {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Retrieves a directory at the given path. Mounts are included.
     pub fn directory(
         &self,
         path: impl Into<String>,
@@ -198,6 +235,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves entrypoint to be prepended to the arguments of all commands.
     pub async fn entrypoint(
         &self,
     ) -> eyre::Result<Vec<String>> {
@@ -205,6 +243,7 @@ impl Container {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Retrieves the value of the specified environment variable.
     pub async fn env_variable(
         &self,
         name: impl Into<String>,
@@ -215,6 +254,7 @@ impl Container {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Retrieves the list of environment variables passed to commands.
     pub fn env_variables(
         &self,
     ) -> Vec<EnvVariable> {
@@ -226,6 +266,11 @@ impl Container {
             conn: self.conn.clone(),
         }]
     }
+    /// Retrieves this container after executing the specified command inside it.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn exec(
         &self,
     ) -> Container {
@@ -238,6 +283,11 @@ impl Container {
         }
     }
 
+    /// Retrieves this container after executing the specified command inside it.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn exec_opts<'a>(
         &self,
         opts: ContainerExecOpts<'a>
@@ -266,6 +316,8 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Exit code of the last executed command. Zero means success.
+    /// Null if no command has been executed.
     pub async fn exit_code(
         &self,
     ) -> eyre::Result<isize> {
@@ -273,6 +325,14 @@ impl Container {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Writes the container as an OCI tarball to the destination file path on the host for the specified platformVariants.
+    /// Return true on success.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `path` - Host's destination path.
+    /// Path can be relative to the engine's workdir or absolute.
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub async fn export(
         &self,
         path: impl Into<String>,
@@ -284,6 +344,14 @@ impl Container {
         query.execute(&graphql_client(&self.conn)).await
     }
 
+    /// Writes the container as an OCI tarball to the destination file path on the host for the specified platformVariants.
+    /// Return true on success.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `path` - Host's destination path.
+    /// Path can be relative to the engine's workdir or absolute.
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub async fn export_opts(
         &self,
         path: impl Into<String>,
@@ -298,6 +366,7 @@ impl Container {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Retrieves a file at the given path. Mounts are included.
     pub fn file(
         &self,
         path: impl Into<String>,
@@ -312,6 +381,12 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Initializes this container from the base image published at the given address.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `address` - Image's address from its registry.
+    /// Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
     pub fn from(
         &self,
         address: impl Into<String>,
@@ -326,6 +401,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container's root filesystem. Mounts are not included.
     pub fn fs(
         &self,
     ) -> Directory {
@@ -337,6 +413,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// A unique identifier for this container.
     pub async fn id(
         &self,
     ) -> eyre::Result<ContainerId> {
@@ -344,6 +421,7 @@ impl Container {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Retrieves the value of the specified label.
     pub async fn label(
         &self,
         name: impl Into<String>,
@@ -354,6 +432,7 @@ impl Container {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Retrieves the list of labels passed to container.
     pub fn labels(
         &self,
     ) -> Vec<Label> {
@@ -365,6 +444,7 @@ impl Container {
             conn: self.conn.clone(),
         }]
     }
+    /// Retrieves the list of paths where a directory is mounted.
     pub async fn mounts(
         &self,
     ) -> eyre::Result<Vec<String>> {
@@ -372,6 +452,11 @@ impl Container {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Creates a named sub-pipeline
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn pipeline(
         &self,
         name: impl Into<String>,
@@ -387,6 +472,11 @@ impl Container {
         }
     }
 
+    /// Creates a named sub-pipeline
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn pipeline_opts<'a>(
         &self,
         name: impl Into<String>,
@@ -405,6 +495,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// The platform this container executes and publishes as.
     pub async fn platform(
         &self,
     ) -> eyre::Result<Platform> {
@@ -412,6 +503,13 @@ impl Container {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Publishes this container as a new image to the specified address, for the platformVariants, returning a fully qualified ref.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `address` - Registry's address to publish the image to.
+    /// Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub async fn publish(
         &self,
         address: impl Into<String>,
@@ -423,6 +521,13 @@ impl Container {
         query.execute(&graphql_client(&self.conn)).await
     }
 
+    /// Publishes this container as a new image to the specified address, for the platformVariants, returning a fully qualified ref.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `address` - Registry's address to publish the image to.
+    /// Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub async fn publish_opts(
         &self,
         address: impl Into<String>,
@@ -437,6 +542,7 @@ impl Container {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Retrieves this container's root filesystem. Mounts are not included.
     pub fn rootfs(
         &self,
     ) -> Directory {
@@ -448,6 +554,8 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// The error stream of the last executed command.
+    /// Null if no command has been executed.
     pub async fn stderr(
         &self,
     ) -> eyre::Result<String> {
@@ -455,6 +563,8 @@ impl Container {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// The output stream of the last executed command.
+    /// Null if no command has been executed.
     pub async fn stdout(
         &self,
     ) -> eyre::Result<String> {
@@ -462,6 +572,7 @@ impl Container {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Retrieves the user to be set for all commands.
     pub async fn user(
         &self,
     ) -> eyre::Result<String> {
@@ -469,6 +580,11 @@ impl Container {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Configures default arguments for future commands.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_default_args(
         &self,
     ) -> Container {
@@ -481,6 +597,11 @@ impl Container {
         }
     }
 
+    /// Configures default arguments for future commands.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_default_args_opts<'a>(
         &self,
         opts: ContainerWithDefaultArgsOpts<'a>
@@ -497,6 +618,11 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container plus a directory written at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_directory(
         &self,
         path: impl Into<String>,
@@ -514,6 +640,11 @@ impl Container {
         }
     }
 
+    /// Retrieves this container plus a directory written at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_directory_opts<'a>(
         &self,
         path: impl Into<String>,
@@ -537,6 +668,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container but with a different command entrypoint.
     pub fn with_entrypoint(
         &self,
         args: Vec<impl Into<String>>,
@@ -551,6 +683,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container plus the given environment variable.
     pub fn with_env_variable(
         &self,
         name: impl Into<String>,
@@ -567,6 +700,12 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container after executing the specified command inside it.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `args` - Command to run instead of the container's default command.
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_exec(
         &self,
         args: Vec<impl Into<String>>,
@@ -582,6 +721,12 @@ impl Container {
         }
     }
 
+    /// Retrieves this container after executing the specified command inside it.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `args` - Command to run instead of the container's default command.
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_exec_opts<'a>(
         &self,
         args: Vec<impl Into<String>>,
@@ -609,6 +754,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Initializes this container from this DirectoryID.
     pub fn with_fs(
         &self,
         id: DirectoryId,
@@ -623,6 +769,11 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container plus the contents of the given file copied to the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_file(
         &self,
         path: impl Into<String>,
@@ -640,6 +791,11 @@ impl Container {
         }
     }
 
+    /// Retrieves this container plus the contents of the given file copied to the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_file_opts(
         &self,
         path: impl Into<String>,
@@ -660,6 +816,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container plus the given label.
     pub fn with_label(
         &self,
         name: impl Into<String>,
@@ -676,6 +833,13 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container plus a cache volume mounted at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `path` - Path to mount the cache volume at.
+    /// * `cache` - ID of the cache to mount.
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_mounted_cache(
         &self,
         path: impl Into<String>,
@@ -693,6 +857,13 @@ impl Container {
         }
     }
 
+    /// Retrieves this container plus a cache volume mounted at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `path` - Path to mount the cache volume at.
+    /// * `cache` - ID of the cache to mount.
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_mounted_cache_opts(
         &self,
         path: impl Into<String>,
@@ -716,6 +887,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container plus a directory mounted at the given path.
     pub fn with_mounted_directory(
         &self,
         path: impl Into<String>,
@@ -732,6 +904,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container plus a file mounted at the given path.
     pub fn with_mounted_file(
         &self,
         path: impl Into<String>,
@@ -748,6 +921,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container plus a secret mounted into a file at the given path.
     pub fn with_mounted_secret(
         &self,
         path: impl Into<String>,
@@ -764,6 +938,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container plus a temporary directory mounted at the given path.
     pub fn with_mounted_temp(
         &self,
         path: impl Into<String>,
@@ -778,6 +953,11 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container plus a new file written at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_new_file(
         &self,
         path: impl Into<String>,
@@ -793,6 +973,11 @@ impl Container {
         }
     }
 
+    /// Retrieves this container plus a new file written at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_new_file_opts<'a>(
         &self,
         path: impl Into<String>,
@@ -814,6 +999,14 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container with a registry authentication for a given address.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `address` - Registry's address to bind the authentication to.
+    /// Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
+    /// * `username` - The username of the registry's account (e.g., "Dagger").
+    /// * `secret` - The API key, password or token to authenticate to this registry.
     pub fn with_registry_auth(
         &self,
         address: impl Into<String>,
@@ -832,6 +1025,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Initializes this container from this DirectoryID.
     pub fn with_rootfs(
         &self,
         id: DirectoryId,
@@ -846,6 +1040,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container plus an env variable containing the given secret.
     pub fn with_secret_variable(
         &self,
         name: impl Into<String>,
@@ -862,6 +1057,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container plus a socket forwarded to the given Unix socket path.
     pub fn with_unix_socket(
         &self,
         path: impl Into<String>,
@@ -878,6 +1074,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this containers with a different command user.
     pub fn with_user(
         &self,
         name: impl Into<String>,
@@ -892,6 +1089,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container with a different working directory.
     pub fn with_workdir(
         &self,
         path: impl Into<String>,
@@ -906,6 +1104,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container minus the given environment variable.
     pub fn without_env_variable(
         &self,
         name: impl Into<String>,
@@ -920,6 +1119,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container minus the given environment label.
     pub fn without_label(
         &self,
         name: impl Into<String>,
@@ -934,6 +1134,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container after unmounting everything at the given path.
     pub fn without_mount(
         &self,
         path: impl Into<String>,
@@ -948,6 +1149,12 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container without the registry authentication of a given address.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `address` - Registry's address to remove the authentication from.
+    /// Formatted as [host]/[user]/[repo]:[tag] (e.g. docker.io/dagger/dagger:main).
     pub fn without_registry_auth(
         &self,
         address: impl Into<String>,
@@ -962,6 +1169,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this container with a previously added Unix socket removed.
     pub fn without_unix_socket(
         &self,
         path: impl Into<String>,
@@ -976,6 +1184,7 @@ impl Container {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves the working directory for all commands.
     pub async fn workdir(
         &self,
     ) -> eyre::Result<String> {
@@ -993,12 +1202,17 @@ pub struct Directory {
 #[derive(Builder, Debug, PartialEq)]
 pub struct DirectoryDockerBuildOpts<'a> {
 
+    /// Path to the Dockerfile to use.
+    /// Defaults to './Dockerfile'.
     #[builder(setter(into, strip_option))]
     pub dockerfile: Option<&'a str>,
+    /// The platform to build.
     #[builder(setter(into, strip_option))]
     pub platform: Option<Platform>,
+    /// Additional build arguments.
     #[builder(setter(into, strip_option))]
     pub build_args: Option<Vec<BuildArg>>,
+    /// Target build stage to build.
     #[builder(setter(into, strip_option))]
     pub target: Option<&'a str>,
 }
@@ -1017,8 +1231,12 @@ pub struct DirectoryPipelineOpts<'a> {
 #[derive(Builder, Debug, PartialEq)]
 pub struct DirectoryWithDirectoryOpts<'a> {
 
+    /// Exclude artifacts that match the given pattern.
+    /// (e.g. ["node_modules/", ".git*"]).
     #[builder(setter(into, strip_option))]
     pub exclude: Option<Vec<&'a str>>,
+    /// Include only artifacts that match the given pattern.
+    /// (e.g. ["app/", "package.*"]).
     #[builder(setter(into, strip_option))]
     pub include: Option<Vec<&'a str>>,
 }
@@ -1042,6 +1260,7 @@ pub struct DirectoryWithNewFileOpts {
 }
 
 impl Directory {
+    /// Gets the difference between this directory and an another directory.
     pub fn diff(
         &self,
         other: DirectoryId,
@@ -1056,6 +1275,7 @@ impl Directory {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves a directory at the given path.
     pub fn directory(
         &self,
         path: impl Into<String>,
@@ -1070,6 +1290,11 @@ impl Directory {
             conn: self.conn.clone(),
         }
     }
+    /// Builds a new Docker container from this directory.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn docker_build(
         &self,
     ) -> Container {
@@ -1082,6 +1307,11 @@ impl Directory {
         }
     }
 
+    /// Builds a new Docker container from this directory.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn docker_build_opts<'a>(
         &self,
         opts: DirectoryDockerBuildOpts<'a>
@@ -1107,6 +1337,11 @@ impl Directory {
             conn: self.conn.clone(),
         }
     }
+    /// Returns a list of files and directories at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub async fn entries(
         &self,
     ) -> eyre::Result<Vec<String>> {
@@ -1115,6 +1350,11 @@ impl Directory {
         query.execute(&graphql_client(&self.conn)).await
     }
 
+    /// Returns a list of files and directories at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub async fn entries_opts<'a>(
         &self,
         opts: DirectoryEntriesOpts<'a>
@@ -1127,6 +1367,7 @@ impl Directory {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Writes the contents of the directory to a path on the host.
     pub async fn export(
         &self,
         path: impl Into<String>,
@@ -1137,6 +1378,7 @@ impl Directory {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Retrieves a file at the given path.
     pub fn file(
         &self,
         path: impl Into<String>,
@@ -1151,6 +1393,7 @@ impl Directory {
             conn: self.conn.clone(),
         }
     }
+    /// The content-addressed identifier of the directory.
     pub async fn id(
         &self,
     ) -> eyre::Result<DirectoryId> {
@@ -1158,6 +1401,7 @@ impl Directory {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// load a project's metadata
     pub fn load_project(
         &self,
         config_path: impl Into<String>,
@@ -1172,6 +1416,11 @@ impl Directory {
             conn: self.conn.clone(),
         }
     }
+    /// Creates a named sub-pipeline.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn pipeline(
         &self,
         name: impl Into<String>,
@@ -1187,6 +1436,11 @@ impl Directory {
         }
     }
 
+    /// Creates a named sub-pipeline.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn pipeline_opts<'a>(
         &self,
         name: impl Into<String>,
@@ -1205,6 +1459,11 @@ impl Directory {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this directory plus a directory written at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_directory(
         &self,
         path: impl Into<String>,
@@ -1222,6 +1481,11 @@ impl Directory {
         }
     }
 
+    /// Retrieves this directory plus a directory written at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_directory_opts<'a>(
         &self,
         path: impl Into<String>,
@@ -1245,6 +1509,11 @@ impl Directory {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this directory plus the contents of the given file copied to the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_file(
         &self,
         path: impl Into<String>,
@@ -1262,6 +1531,11 @@ impl Directory {
         }
     }
 
+    /// Retrieves this directory plus the contents of the given file copied to the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_file_opts(
         &self,
         path: impl Into<String>,
@@ -1282,6 +1556,11 @@ impl Directory {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this directory plus a new directory created at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_new_directory(
         &self,
         path: impl Into<String>,
@@ -1297,6 +1576,11 @@ impl Directory {
         }
     }
 
+    /// Retrieves this directory plus a new directory created at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_new_directory_opts(
         &self,
         path: impl Into<String>,
@@ -1315,6 +1599,11 @@ impl Directory {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this directory plus a new file written at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_new_file(
         &self,
         path: impl Into<String>,
@@ -1332,6 +1621,11 @@ impl Directory {
         }
     }
 
+    /// Retrieves this directory plus a new file written at the given path.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn with_new_file_opts(
         &self,
         path: impl Into<String>,
@@ -1352,6 +1646,7 @@ impl Directory {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this directory with all file/dir timestamps set to the given time, in seconds from the Unix epoch.
     pub fn with_timestamps(
         &self,
         timestamp: isize,
@@ -1366,6 +1661,7 @@ impl Directory {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this directory with the directory at the given path removed.
     pub fn without_directory(
         &self,
         path: impl Into<String>,
@@ -1380,6 +1676,7 @@ impl Directory {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves this directory with the file at the given path removed.
     pub fn without_file(
         &self,
         path: impl Into<String>,
@@ -1402,6 +1699,7 @@ pub struct EnvVariable {
 }
 
 impl EnvVariable {
+    /// The environment variable name.
     pub async fn name(
         &self,
     ) -> eyre::Result<String> {
@@ -1409,6 +1707,7 @@ impl EnvVariable {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// The environment variable value.
     pub async fn value(
         &self,
     ) -> eyre::Result<String> {
@@ -1424,6 +1723,7 @@ pub struct File {
 }
 
 impl File {
+    /// Retrieves the contents of the file.
     pub async fn contents(
         &self,
     ) -> eyre::Result<String> {
@@ -1431,6 +1731,7 @@ impl File {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Writes the file to a file path on the host.
     pub async fn export(
         &self,
         path: impl Into<String>,
@@ -1441,6 +1742,7 @@ impl File {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Retrieves the content-addressed identifier of the file.
     pub async fn id(
         &self,
     ) -> eyre::Result<FileId> {
@@ -1448,6 +1750,7 @@ impl File {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Retrieves a secret referencing the contents of this file.
     pub fn secret(
         &self,
     ) -> Secret {
@@ -1459,6 +1762,7 @@ impl File {
             conn: self.conn.clone(),
         }
     }
+    /// Gets the size of the file, in bytes.
     pub async fn size(
         &self,
     ) -> eyre::Result<isize> {
@@ -1466,6 +1770,7 @@ impl File {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Retrieves this file with its created/modified timestamps set to the given time, in seconds from the Unix epoch.
     pub fn with_timestamps(
         &self,
         timestamp: isize,
@@ -1497,6 +1802,7 @@ pub struct GitRefTreeOpts<'a> {
 }
 
 impl GitRef {
+    /// The digest of the current value of this ref.
     pub async fn digest(
         &self,
     ) -> eyre::Result<String> {
@@ -1504,6 +1810,11 @@ impl GitRef {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// The filesystem tree at this ref.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn tree(
         &self,
     ) -> Directory {
@@ -1516,6 +1827,11 @@ impl GitRef {
         }
     }
 
+    /// The filesystem tree at this ref.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn tree_opts<'a>(
         &self,
         opts: GitRefTreeOpts<'a>
@@ -1543,6 +1859,7 @@ pub struct GitRepository {
 }
 
 impl GitRepository {
+    /// Returns details on one branch.
     pub fn branch(
         &self,
         name: impl Into<String>,
@@ -1557,6 +1874,7 @@ impl GitRepository {
             conn: self.conn.clone(),
         }
     }
+    /// Lists of branches on the repository.
     pub async fn branches(
         &self,
     ) -> eyre::Result<Vec<String>> {
@@ -1564,6 +1882,7 @@ impl GitRepository {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Returns details on one commit.
     pub fn commit(
         &self,
         id: impl Into<String>,
@@ -1578,6 +1897,7 @@ impl GitRepository {
             conn: self.conn.clone(),
         }
     }
+    /// Returns details on one tag.
     pub fn tag(
         &self,
         name: impl Into<String>,
@@ -1592,6 +1912,7 @@ impl GitRepository {
             conn: self.conn.clone(),
         }
     }
+    /// Lists of tags on the repository.
     pub async fn tags(
         &self,
     ) -> eyre::Result<Vec<String>> {
@@ -1624,6 +1945,11 @@ pub struct HostWorkdirOpts<'a> {
 }
 
 impl Host {
+    /// Accesses a directory on the host.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn directory(
         &self,
         path: impl Into<String>,
@@ -1639,6 +1965,11 @@ impl Host {
         }
     }
 
+    /// Accesses a directory on the host.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn directory_opts<'a>(
         &self,
         path: impl Into<String>,
@@ -1660,6 +1991,7 @@ impl Host {
             conn: self.conn.clone(),
         }
     }
+    /// Accesses an environment variable on the host.
     pub fn env_variable(
         &self,
         name: impl Into<String>,
@@ -1674,6 +2006,7 @@ impl Host {
             conn: self.conn.clone(),
         }
     }
+    /// Accesses a Unix socket on the host.
     pub fn unix_socket(
         &self,
         path: impl Into<String>,
@@ -1688,6 +2021,11 @@ impl Host {
             conn: self.conn.clone(),
         }
     }
+    /// Retrieves the current working directory on the host.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn workdir(
         &self,
     ) -> Directory {
@@ -1700,6 +2038,11 @@ impl Host {
         }
     }
 
+    /// Retrieves the current working directory on the host.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn workdir_opts<'a>(
         &self,
         opts: HostWorkdirOpts<'a>
@@ -1727,6 +2070,7 @@ pub struct HostVariable {
 }
 
 impl HostVariable {
+    /// A secret referencing the value of this variable.
     pub fn secret(
         &self,
     ) -> Secret {
@@ -1738,6 +2082,7 @@ impl HostVariable {
             conn: self.conn.clone(),
         }
     }
+    /// The value of this variable.
     pub async fn value(
         &self,
     ) -> eyre::Result<String> {
@@ -1753,6 +2098,7 @@ pub struct Label {
 }
 
 impl Label {
+    /// The label name.
     pub async fn name(
         &self,
     ) -> eyre::Result<String> {
@@ -1760,6 +2106,7 @@ impl Label {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// The label value.
     pub async fn value(
         &self,
     ) -> eyre::Result<String> {
@@ -1775,6 +2122,7 @@ pub struct Project {
 }
 
 impl Project {
+    /// extensions in this project
     pub fn extensions(
         &self,
     ) -> Vec<Project> {
@@ -1786,6 +2134,7 @@ impl Project {
             conn: self.conn.clone(),
         }]
     }
+    /// Code files generated by the SDKs in the project
     pub fn generated_code(
         &self,
     ) -> Directory {
@@ -1797,6 +2146,7 @@ impl Project {
             conn: self.conn.clone(),
         }
     }
+    /// install the project's schema
     pub async fn install(
         &self,
     ) -> eyre::Result<bool> {
@@ -1804,6 +2154,7 @@ impl Project {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// name of the project
     pub async fn name(
         &self,
     ) -> eyre::Result<String> {
@@ -1811,6 +2162,7 @@ impl Project {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// schema provided by the project
     pub async fn schema(
         &self,
     ) -> eyre::Result<String> {
@@ -1818,6 +2170,7 @@ impl Project {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// sdk used to generate code for and/or execute this project
     pub async fn sdk(
         &self,
     ) -> eyre::Result<String> {
@@ -1866,6 +2219,11 @@ pub struct QuerySocketOpts {
 }
 
 impl Query {
+    /// Constructs a cache volume for a given cache key.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `key` - A string identifier to target this cache volume (e.g. "myapp-cache").
     pub fn cache_volume(
         &self,
         key: impl Into<String>,
@@ -1880,6 +2238,13 @@ impl Query {
             conn: self.conn.clone(),
         }
     }
+    /// Loads a container from ID.
+    /// Null ID returns an empty container (scratch).
+    /// Optional platform argument initializes new containers to execute and publish as that platform. Platform defaults to that of the builder's host.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn container(
         &self,
     ) -> Container {
@@ -1892,6 +2257,13 @@ impl Query {
         }
     }
 
+    /// Loads a container from ID.
+    /// Null ID returns an empty container (scratch).
+    /// Optional platform argument initializes new containers to execute and publish as that platform. Platform defaults to that of the builder's host.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn container_opts(
         &self,
         opts: QueryContainerOpts
@@ -1911,6 +2283,7 @@ impl Query {
             conn: self.conn.clone(),
         }
     }
+    /// The default platform of the builder.
     pub async fn default_platform(
         &self,
     ) -> eyre::Result<Platform> {
@@ -1918,6 +2291,11 @@ impl Query {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// Load a directory by ID. No argument produces an empty directory.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn directory(
         &self,
     ) -> Directory {
@@ -1930,6 +2308,11 @@ impl Query {
         }
     }
 
+    /// Load a directory by ID. No argument produces an empty directory.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn directory_opts(
         &self,
         opts: QueryDirectoryOpts
@@ -1946,6 +2329,7 @@ impl Query {
             conn: self.conn.clone(),
         }
     }
+    /// Loads a file by ID.
     pub fn file(
         &self,
         id: FileId,
@@ -1960,6 +2344,11 @@ impl Query {
             conn: self.conn.clone(),
         }
     }
+    /// Queries a git repository.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn git(
         &self,
         url: impl Into<String>,
@@ -1975,6 +2364,11 @@ impl Query {
         }
     }
 
+    /// Queries a git repository.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn git_opts(
         &self,
         url: impl Into<String>,
@@ -1993,6 +2387,7 @@ impl Query {
             conn: self.conn.clone(),
         }
     }
+    /// Queries the host environment.
     pub fn host(
         &self,
     ) -> Host {
@@ -2004,6 +2399,7 @@ impl Query {
             conn: self.conn.clone(),
         }
     }
+    /// Returns a file containing an http remote url content.
     pub fn http(
         &self,
         url: impl Into<String>,
@@ -2018,6 +2414,11 @@ impl Query {
             conn: self.conn.clone(),
         }
     }
+    /// Creates a named sub-pipeline
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn pipeline(
         &self,
         name: impl Into<String>,
@@ -2033,6 +2434,11 @@ impl Query {
         }
     }
 
+    /// Creates a named sub-pipeline
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn pipeline_opts<'a>(
         &self,
         name: impl Into<String>,
@@ -2051,6 +2457,7 @@ impl Query {
             conn: self.conn.clone(),
         }
     }
+    /// Look up a project by name
     pub fn project(
         &self,
         name: impl Into<String>,
@@ -2065,6 +2472,7 @@ impl Query {
             conn: self.conn.clone(),
         }
     }
+    /// Loads a secret from its ID.
     pub fn secret(
         &self,
         id: SecretId,
@@ -2079,6 +2487,11 @@ impl Query {
             conn: self.conn.clone(),
         }
     }
+    /// Loads a socket by its ID.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn socket(
         &self,
     ) -> Socket {
@@ -2091,6 +2504,11 @@ impl Query {
         }
     }
 
+    /// Loads a socket by its ID.
+    /// 
+    /// # Arguments
+    /// 
+    /// * `opt` - optional argument, see inner type for documentation, use <func>_opts to use
     pub fn socket_opts(
         &self,
         opts: QuerySocketOpts
@@ -2115,6 +2533,7 @@ pub struct Secret {
 }
 
 impl Secret {
+    /// The identifier for this secret.
     pub async fn id(
         &self,
     ) -> eyre::Result<SecretId> {
@@ -2122,6 +2541,7 @@ impl Secret {
 
         query.execute(&graphql_client(&self.conn)).await
     }
+    /// The value of this secret.
     pub async fn plaintext(
         &self,
     ) -> eyre::Result<String> {
@@ -2137,6 +2557,7 @@ pub struct Socket {
 }
 
 impl Socket {
+    /// The content-addressed identifier of the socket.
     pub async fn id(
         &self,
     ) -> eyre::Result<SocketId> {