`#:` task description doesn't work if target is prefixed with `.PHONY` declaration

[falko]

The best practice is to:

add each phony target as a prerequisite of .PHONY immediately before the target declaration, rather than listing all the phony targets in a single place.

However, if I put a remake task description in front of it, remake --tasks won't show it because .PHONY is a target of its own.

Example:

#: This is the main target
.PHONY: all
all:
    echo "Executing all ..."

Workarounds:

1. Leave out the .PHONY declaration as in your example and risk hard to debug behavior when a file with the name of the target exists.
2. Put the .PHONY declaration below the target or elsewhere and risk name mismatches or forgetting to declare phony targets. I've seen that happening even with .PHONY directly above the target.

[rocky]

You can also move the #: comment down a line like this:

.PHONY: all
#: This is the main target
all:
     echo "Executing all ..."

and in my opinion this is more precise. The comment is about the "all" target, not that the "all" target happens to be "phony" or have no file associated with it.

In another Makefile or this Makefile evolved over time you might have:

#: This is the main target
.PHONY: all check
all:
    echo "Executing all ..."
check: 
    echo "Do the steps needed to test this package"

And that comment would be misleading.

I believe the reason the comment does not show up (it's been a while) is because the .PHONY target does not have code associated with it just "dependency" information (which doesn't feel like a dependency here, but that's make for you).

In the above examples, the target(s) that have code associated with it are "all" in the first example and in the second example "all" and "check".

If you feel strongly about changing this and are up for it feel free to dig into the code and change things.