Documentation inconsistencies

Oct 13, 2025 by talynt.org 118 views

mix xref graph output options: inconsistent and misleading documentation

Elixir and Erlang/OTP versions

The issues described in this article were encountered while working on Elixir 1.18.2, which is compiled with Erlang/OTP 27. The Elixir and Erlang/OTP versions are as follows:

$ 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

The issues described in this article were encountered on a macOS operating system. However, it is worth noting that this is not an OS-specific issue.

Current behavior

Documentation inconsistencies

Documentation for mix xref graph: The documentation for mix xref graph suggests that the --output option governs all forms of output. However, in fact, it only affects the dot format. The documentation states:

  • --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, as 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.

Verbiage for dot format: When the dot format is used, verbiage is produced explaining how one can use the dot application to turn the output into a graph. However, this verbiage is incorrect when the --output option is used to write the file to a different location than the current working directory. For example:

$ 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/.

This is incorrect because the file is not generated in the current directory, but rather in the specified location.

Expected behavior

Clarify documentation: The documentation for mix xref graph should be clarified to indicate that the --output option only affects the dot format. Alternatively, the code should be modified to make the --output option apply to all output formats.
Smarter verbiage: The verbiage produced when using the dot format should be smarter and should not mention "the current directory" unless the file lacks a directory specification. For example:

$ 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/.

Verbose option: The verbiage in 2 should only be produced when a --verbose option is used.

Conclusion

The mix xref graph command has several output options, including --output and --format. However, the documentation for these options is inconsistent and, in some cases, misleading. This article has highlighted the issues with the current behavior and proposed expected behavior. By clarifying the documentation and modifying the code to make the --output option apply to all output formats, the mix xref graph command can be made more user-friendly and easier to use.

Proposed changes

The following changes are proposed to address the issues described in this article:

Modify documentation: Clarify the documentation for mix xref graph to indicate that the --output option only affects the dot format.
Modify code: Modify the code to make the --output option apply to all output formats.
Add verbose option: Add a --verbose option to produce the verbiage in 2 only when specified.

By implementing these changes, the mix xref graph command can be made more user-friendly and easier to use.
mix xref graph output options: Q&A

Q: What is the purpose of the `--output` option in `mix xref graph`?

A: The --output option is used to specify the output file for the dot format. However, the documentation is inconsistent and, in some cases, misleading.

Q: What is the expected behavior of the `--output` option?

A: The expected behavior of the --output option is to apply to all output formats, not just the dot format. This would allow users to specify the output file for any format, not just dot.

Q: Why is the verbiage for the `dot` format incorrect?

A: The verbiage for the dot format is incorrect because it mentions "the current directory" when the file is actually written to a different location. This can be confusing for users who are not familiar with the command.

Q: What is the proposed solution to address the issues with the `--output` option?

A: The proposed solution is to modify the documentation to clarify the behavior of the --output option and to modify the code to make the --output option apply to all output formats.

Q: What is the benefit of adding a `--verbose` option?

A: The benefit of adding a --verbose option is to allow users to control the amount of output produced by the command. This would make the command more user-friendly and easier to use.

Q: How can users contribute to improving the `mix xref graph` command?

A: Users can contribute to improving the mix xref graph command by submitting patches or pull requests to the Elixir repository. This would allow the community to review and test the changes before they are merged into the main codebase.

Q: What is the timeline for implementing the proposed changes?

A: The timeline for implementing the proposed changes is not yet determined. However, it is expected that the changes will be implemented in the near future, pending community feedback and testing.

Q: How can users stay up-to-date with the latest developments on the `mix xref graph` command?

A: Users can stay up-to-date with the latest developments on the mix xref graph command by following the Elixir blog and repository on GitHub. This would allow users to stay informed about the latest changes and updates to the command.

Q: What is the expected outcome of implementing the proposed changes?

A: The expected outcome of implementing the proposed changes is to make the mix xref graph command more user-friendly and easier to use. This would improve the overall experience for users and make it easier for them to generate and visualize code references.

Q: How can users provide feedback on the proposed changes?

A: Users can provide feedback on the proposed changes by submitting comments or issues on the Elixir repository on GitHub. This would allow the community to review and discuss the changes before they are implemented.

Q: What is the next step in implementing the proposed changes?

A: The next step in implementing the proposed changes is to submit a pull request to the Elixir repository with the modified code and documentation. This would allow the community to review and test the changes before they are merged into the main codebase.