Ability to nest code to improve readability

[cowwoc]

Is your enhancement related to a problem? Please describe

One of my main pain points when using this API is the indentation level. When I create a resource, all the methods end up on the same level which makes the code much harder to read.

Is there a way to nest some DSLs inside others?

Describe the solution you'd like

For example l, instead of:

Pod pod = new PodBuilder()
    .withNewMetadata()
    .withName("example-pod")
    .withNamespace("default")
    .endMetadata()
    .withSpec(spec)
    .build();

I'd prefer:

Pod pod = new PodBuilder()
    .withNewMetadata(m -> m
        .withName("example-pod")
        .withNamespace("default")
    .endMetadata()
    .withSpec(spec)
    .build();

It seems like a small changes, but when real-life code contains 20-30 method calls in a row it makes a huge difference.

The official Java library for Kubernetes offers something like this (but their usability is worse in every other way). Is there a way to do this with this library?

Describe alternatives you've considered

No response

Additional context

No response

[cowwoc]

Never. I think that withMetadata()-style methods already do what I'm asking for. Sorry for the noise.

[manusa]

Following is an example of the pattern I tend to follow to allow for readability and autoformat coexistence:

new DeploymentBuilder()
      .withMetadata(new ObjectMetaBuilder()
        .withName(NAME)
        .addToLabels(APP, APP_LABEL)
        .build()
      )
      .withSpec(new DeploymentSpecBuilder()
        .withReplicas(1)
        .withNewSelector()
        .addToMatchLabels(APP, APP_LABEL)
        .endSelector()
        .withNewTemplate()
        .withNewMetadata()
        .addToLabels(APP, APP_LABEL)
        .endMetadata()
        .withNewSpec()
        .addToContainers(new ContainerBuilder()
          .withName(NAME)
          /* ... */
          .build())
        .addToVolumes(new VolumeBuilder()
          .withName(NAME)
          .withNewPersistentVolumeClaim()
          .withClaimName(NAME)
          .endPersistentVolumeClaim()
          .build())
        .endSpec()
        .endTemplate()
        .build())
      .build();

In case you want indentation, just use the withXxx instead of the withNewXxx accessor and the appropriate builder.
By combining both, you take control of what gets nested and force the readers attention to wherever is necessary.

[cowwoc]

Yeah, that's what I ended up doing in the end. It works great. Thank you.

PS: Where can I find documentation that discusses all these things (the difference between the various API methods)? I understand that the code is auto-generated, but wouldn't it be possible to auto-generate some Javadoc to go along with it as well? I noticed that the vast majority of the methods have no Javadoc at all... :(

[manusa]

If you're referring to the Javadoc that goes along with the builders, this is something that needs to be looked into.

As a follow up to #6130 I want to add the docs to the model types (you just reminded me to create the issue 😅), which is now possible with the new approach to generation.
However, AFAIR there's still a limitation on https://github.com/sundrio/sundrio/ that won't propagate these docs to the builder classes and that will need to be looked into.

[cowwoc]

@manusa I'm super happy you're working on this. Honestly, this is awesome news. Too many open-source projects treat Javadoc as an afterthought and it wastes users a lot of time. Thank you.