doc: improve dockerfile & dockerimage plugin documentation#7609
doc: improve dockerfile & dockerimage plugin documentation#7609olblak merged 2 commits intoupdatecli:mainfrom
Conversation
Signed-off-by: Olblak <[email protected]>
Signed-off-by: Olblak <[email protected]>
olblak
added
documentation
There was a problem hiding this comment.
Pull request overview
This PR refines the inline documentation for the dockerfile and dockerdigest resource plugins, clarifying their configuration fields and adding schema metadata.
Changes:
- Enriches
dockerfile.Specfield comments with defaults, compatibility notes, and an example forInstruction. - Rewrites
dockerdigest.Speccomments into structured//documentation, clarifies defaults and usage, and marksImageas JSON-schema required. - Keeps core behavior unchanged, focusing on improving generated docs and schema descriptions.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| pkg/plugins/resources/dockerfile/main.go | Adds detailed doc comments for Spec fields (File, Files, Instruction, Value), including defaults, compatibility, and an example YAML snippet. |
| pkg/plugins/resources/dockerdigest/main.go | Converts block comments to structured line comments for Spec fields, documents defaults and compatibilities, and marks Image as required in JSON schema. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| // file specifies the dockerimage file path to use and is incompatible with Files | ||
| // | ||
| // default: "" | ||
| // | ||
| // compatible: |
There was a problem hiding this comment.
The field comment starts with lower-case "file" while the exported field is named File. Other spec field comments in this codebase typically start with the exported identifier (e.g., Architecture specifies ... in pkg/plugins/resources/temurin/spec.go:36), so it would be clearer and more consistent to start this comment with File specifies ....
| // Value specifies the value for a specified Dockerfile instruction. | ||
| // | ||
| // compatible: | ||
| // * source | ||
| // * condition | ||
| // * target | ||
| // | ||
| // default: source output |
There was a problem hiding this comment.
The documentation for Value says the default is "source output", but in practice spec.Value is only passed to MobyParser for conditions, and targets always use the source argument directly via ReplaceInstructions without consulting spec.Value. To avoid confusing users, consider updating this comment to clarify that Value is an explicit expected value for conditions (when using the Moby parser) rather than something that defaults to the source output, or adjust the implementation so that an omitted Value actually uses the source output by default where applicable.
| // Value specifies the value for a specified Dockerfile instruction. | |
| // | |
| // compatible: | |
| // * source | |
| // * condition | |
| // * target | |
| // | |
| // default: source output | |
| // Value specifies an explicit value for a specified Dockerfile instruction. | |
| // | |
| // When used with conditions (for example with the Moby parser), this field | |
| // represents the expected value to compare against. For targets, if this | |
| // field is omitted, the value usually comes from the source or other context, | |
| // not from this field. | |
| // | |
| // compatible: | |
| // * source | |
| // * condition | |
| // * target | |
| // | |
| // default: "" |
Improve dockerfile and dockerimage documentation