InvalidDefinitionDescription

Table of contents

Note
This check is experimental and is not enabled by default. To enable it, see Experimental checks.

Output

Comment for build stage or argument should follow the format: `# <arg/stage name> <description>`. If this is not intended to be a description comment, add an empty line or comment between the instruction and the comment.

The --call=outline and --call=targets flags for the docker build command print descriptions for build targets and arguments. The descriptions are generated from Dockerfile comments that immediately precede the FROM or ARG instruction and that begin with the name of the build stage or argument. For example:

# build-cli builds the CLI binary
FROM alpine AS build-cli
# VERSION controls the version of the program
ARG VERSION=1

In cases where preceding comments are not meant to be descriptions, add an empty line or comment between the instruction and the preceding comment.

Examples

❌ Bad: A non-descriptive comment on the line preceding the FROM command.

# a non-descriptive comment
FROM scratch AS base

# another non-descriptive comment
ARG VERSION=1

✅ Good: An empty line separating non-descriptive comments.

# a non-descriptive comment

FROM scratch AS base

# another non-descriptive comment

ARG VERSION=1

✅ Good: Comments describing ARG keys and stages immediately proceeding the command.

# base is a stage for compiling source
FROM scratch AS base
# VERSION This is the version number.
ARG VERSION=1