stack clean should be documented better

[jwaldmann]

This command is mentioned in the online docs only very briefly ("clean" appears two times on http://docs.haskellstack.org/en/stable/GUIDE/) but its semantics is not defined.

I think "how to delete results from earlier builds/trigger a rebuild" is a basic question. I can understand that the one true answer is "you don't, because builds are deterministic", but sometimes they are not (see issue #2277).

The executable is more helpful

 stack clean --help
Usage: stack clean ([PACKAGE] | [--full]) [--help]
  Clean the local packages

Available options:
  PACKAGE                  If none specified, clean all local packages
  --full                   Delete all work directories (.stack-work by default)

but I still don't know what "clean a package" means.

My suggestion is to (keep this output, but) add a paragraph to the (online) docs. In fact, I'd expect that I would find there: a list of all stack commands, and then for each of them, a description of what it does. Instead, the User Guide is a mixture of motivation and tutorial. That's useful, but it leaves some questions open. (Yes, I know it's hard to get people to write documentation ...)

[simonmichael]

Agreed, It should be easy to navigate to the online doc for each command.

[ygale]

I agree with the goal of making it easier to navigate the guide to find each command. However, to keep the focus, the ask in this issue is to document what stack clean does.

[dbaynard]

to document what stack clean does

That is part of the above PR. The next version will document that.

For the current versions (1.9.3 and below):

• stack clean deletes the dist directories named for the version of Cabal bundled with the GHC used by the resolver. This corresponds to the build artefacts.
• stack clean --full deletes dist and install directories — I believe all the dist directories (not just the ones corresponding to the specific Cabal version).

The change is a simplification (which means GHC will not be needed for stack clean to work) wherein stack clean deletes all build artefacts and stack purge deletes build artefacts and outputs.

Neither do anything for snapshot files, e.g. snapshot dependencies.