Multi line documentation comment

[hyzyla]

I have such recipe

# Build python image for ARM arhcitecture. 
#
# We are building directly by docker command, because docker-compsoe doesn't support 
# different Dockerfiles for different processor architectures
build-python-arm-image:
    docker build --file config/docker/py.ARM.dockerfile --target dev --tag my-image .

What I was expected to see in documentation:

# just --list
Available recipes:
    build-python-arm-image # Build python image for ARM arhcitecture.

What I've got:

# just --list
Available recipes:
    build-python-arm-image # different Dockerfiles for different processor architectures

Is it possible to add support for multiline documentation comments, in such way that first line or all lines should be presented in documenation?

[casey]

It's a bit awkward, but you could do this:

# We are building directly by docker command, because docker-compsoe doesn't support 
# different Dockerfiles for different processor architectures
#
# Build python image for ARM architecture. 
build-python-arm-image:
    docker build --file config/docker/py.ARM.dockerfile --target dev --tag my-image .

It's definitely not ideal!

We could change doc comments to use the first comment line, instead of the last. Or to use all lines. Someone would have to survey justfiles on GitHub and see how disruptive this would be. I'd be open to it, if it wouldn't be super disruptive, since it wouldn't actually break anything.

[runeimp]

Sound like another good candidate for the Just Editions concept

[casey]

@runeimp Definitely. In fact, there are few things that I'd like to reform about doc-comments:

#553
#1273
#495

[casey]

Better late than never! #2050 added a [doc] attribute, so you can set a recipe's doc comment with [doc(STRING)] and string can be multiple lines, which will override any # … comments, if present.