dialyzer: Document the meaning of specs

[TD5]

Add a section in Dialyzer's docs to expand on how specs are checked and used to refine Dialyzer's inferred types, since this is often a point of confusion.

[github-actions]

CT Test Results

    2 files    38 suites   16m 45s ⏱️
450 tests 447 ✔️ 3 💤 0 ❌
536 runs  533 ✔️ 3 💤 0 ❌

Results for commit 5853e6f.

♻️ This comment has been updated with latest results.

To speed up review, make sure that you have read Contributing to Erlang/OTP and that all checks pass.

See the TESTING and DEVELOPMENT HowTo guides for details about how to run test locally.

Artifacts

• Complete CT logs (Download Logs)
• HTML Documentation (Download HTML Docs)
• Windows Installer

// Erlang/OTP Github Action Bot

[garazdawi]

Would it make sense to add some examples to showcase some common mistakes in this area?

[TD5]

Thanks for your suggestion @garazdawi. I've added some examples of how specs and inferred type interact, and some context explaining the potential implications. I am open to suggestions around the wording, etc.

[garazdawi]

One additional thought, would it make sense to mention -Woverspecs in the text as a tool to find these problem areas?

The text looks good to me, but I'll leave the final review to @bjorng as he is both better at Dialyzer and reviewing English than I am.

[TD5]

One additional thought, would it make sense to mention -Woverspecs in the text as a tool to find these problem areas?

The text looks good to me, but I'll leave the final review to @bjorng as he is both better at Dialyzer and reviewing English than I am.

Good question. In short, I am not entirely sure of the meaning of -Woverspecs. For example, overspec'ing a function argument would be bad, but overspec'ing a return would be fine, but I am not sure whether this new option considers variance like that (most of the code I've seen does not).

I also suspect it would suffer from the problem of generating false-positives, as with #6243

[bjorng]

I find the examples confusing. I have pushed a suggestion for making the example more concrete as a fixup commit. Please have a look and feel free to further clarify and improve.

[TD5]

Thanks for your touch ups to make these docs much more clear, @garazdawi & @bjorng: I've squashed them into the original commit.

[bjorng]

Thanks!

[hanssv]

@TD5 there is a typo on line 291... Dialyzer will infer a | b -> binary() not b | c -> binary().

[bjorng]

@hanssv Thanks! Corrected.