mix xref graph output options, documentation and verbiage are inconsistent and in some cases misleading

[demerphq]

Elixir and Erlang/OTP versions

$ elixir --version
Erlang/OTP 27 [erts-15.2.2] [source] [64-bit] [smp:11:11] [ds:11:11:10] [async-threads:1] [jit]

Elixir 1.18.2 (compiled with Erlang/OTP 27)

Operating system

macos (Not Applicable - this is not an OS specific issue)

Current behavior

This is a generic ticket covering several documentation and option inconsistencies and bugs related to the --output and --format options associated with mix xref graph. I noticed these issues while working on adding support JSON output.

1. Documentation for mix xref graph seems to suggest that the --output option governs all forms of output, but in fact currently only affects the dot format. Eg:

  • --output (since v1.15.0) - can be set to one of
    • - - prints the output to standard output;

    • a path - writes the output graph to the given path

    Defaults to xref_graph.dot in the current directory.

This is a bit muddled, it says "the output" and the structure of the documentation suggests this is a general option, but at the same time it says the default is "xref_graph.dot" which implies that refers only to the dot format output.

2. When the 'dot' format is used verbiage is produced explaining how one can use the 'dot' application to turn the output into a graph. This verbiage is incorrect when the --output option is used to write the file to a different location than the current working directory. Eg:

$ mix xref graph --format=dot --output=/tmp/graph.dot
Generated "/tmp/graph.dot" in the current directory. To generate a PNG:

   dot -Tpng "/tmp/graph.dot" -o "graph.png"

For more options see http://www.graphviz.org/.

3. I think it should be possible to silence the verbiage mentioned in 2 above, or that the verbiage should not be produced unless a verbose option is selected.

Expected behavior

1. Either the documentation is wrong and it should be clarified that the --output option applies only to the dot format, or (my preference) the code is wrong, and the output option should apply to all output formats. IMO, specifying --output=/tmp/file.txt without specifying the format should result in the normal output being written to /tmp/file.txt, just as it would override where the 'dot' formatted output is written.

I favour making the --output option apply to all output formats of mix xref graph as I would like to use this with the new json format support I am adding, and i see no reason I shouldn't be able to write the plain or pretty output to a file without using output redirection where the output might include artefacts about the compilation process, or other verbiage.

2. IMO the verbiage should be smarter and should not mention "the current directory" unless the file lacks a directory specification. Something like this:

$ mix xref graph --format=dot --output=/tmp/graph.dot
Generated "/tmp/graph.dot". To generate a PNG:

   dot -Tpng "/tmp/graph.dot" -o "graph.png"

For more options see http://www.graphviz.org/.

3. IMO the verbiage in 2 should only be produced when a (hypothetical) --verbose option is used.

FWIW, I noticed these issues as I was working on adding support for 'json' output format. I have patches for some of them that I will include in a PR adding this new output discipline.

[josevalim]

Closing this in favor of #14327. The PR solves 1 and 2, and 3 can be solved with MIX_QUIET=1 mix xref graph --format dot :)