deny(missing_docs) vs derive(CustomResource)

[olix0r]

Is it possible to document types generated with kube::CustomResource?

For example:

#![deny(missing_docs)]

/// HTTPRoute provides a way to route HTTP requests. This includes the
/// capability to match requests by hostname, path, header, or query param.
/// Filters can be used to specify additional processing steps. Backends specify
/// where matching requests should be routed.
#[derive(
    Clone, Debug, kube::CustomResource, serde::Deserialize, serde::Serialize, schemars::JsonSchema,
)]
#[kube(
    group = "gateway.networking.k8s.io/v1alpha2",
    version = "v1alpha2",
    kind = "HttpRoute",
    status = "HttpRouteStatus",
    namespaced
)]
#[serde(rename_all = "camelCase")]
pub struct HttpRouteSpec {
    // ...
}

error: missing documentation for a struct field
  --> src/v1alpha2/httproute.rs:18:1
   |
18 | pub struct HttpRouteSpec {
   | ^^^^^^^^^^^^^^^^^^^^^^^^

error: missing documentation for an associated function
 --> src/v1alpha2/httproute.rs:8:19
  |
8 |     Clone, Debug, kube::CustomResource, serde::Deserialize, serde::Serialize, schemars::JsonSchema,
  |                   ^^^^^^^^^^^^^^^^^^^^
  |
  = note: this error originates in the derive macro `kube::CustomResource` (in Nightly builds, run with -Z macro-backtrace for more info)

If it's not possible today, are there any thoughts on how to best solve this problem?

[clux]

Oh, that's a strange error. The documentation is actually preserved on the struct as can be seen at the beginning of cargo expand that_file

Tried it on the crd_apply example with some examples and it propagates correctly (and even inserts a dummy comment on the one generated struct):

/// Comment before FooSpec
#[kube(group = "clux.dev", version = "v1", kind = "Foo", namespaced)]
#[kube(status = "FooStatus")]
#[kube(scale = r#"{"specReplicasPath":".spec.replicas", "statusReplicasPath":".status.replicas"}"#)]
pub struct FooSpec {
    name: String,
    info: Option<String>,
    replicas: isize,
}
/// Auto-generated derived type for FooSpec via `CustomResource`
#[serde(rename_all = "camelCase")]
pub struct Foo {
    #[schemars(skip)]
    pub metadata: ::k8s_openapi::apimachinery::pkg::apis::meta::v1::ObjectMeta,
    pub spec: FooSpec,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub status: Option<FooStatus>,
}
...
/// Comment before FooStatus
pub struct FooStatus {
    is_bad: bool,
    replicas: isize,
}

but yeah, rustc definitely complains, have found one the reasons; the Foo::new impl

impl Foo {
    pub fn new(name: &str, spec: FooSpec) -> Self {
        Self {
            metadata: ::k8s_openapi::apimachinery::pkg::apis::meta::v1::ObjectMeta {
                name: Some(name.to_string()),
                ..Default::default()
            },
            spec: spec,
            status: None,
        }
    }
}

and we can fix that in kube-derive, but not sure about where the others come from yet.

[clux]

Ah, the generated members for Foo (metadata, spec, status (if exists)) need docs as well because they inherit the pub visibility. This can all be fixed in kube-derive.

[olix0r]

Thanks for the clarification!

[clux]

PR for the fix in #919. Thanks for the issue!