Automatic Static Analysis Tools (ASATs) are widely used by software developers to diffuse and enforce coding practices. Yet, we know little about the documentation of ASATs, despite it being critical to learn about the coding practices in the first place. We shed light on this through several contributions. First, we analyze the documentation of more than 100 rules of 16 ASATs for multiple programming languages, and distill a taxonomy of the purposes of the documentation-What triggers a rule; Why it is important; and how to Fix an issue-and its types of contents. Then, we conduct a survey to assess the effectiveness of the documentation in terms of its goals and types of content. We highlight opportunities for improvement in ASAT documentation. In particular, we find that the Why purpose is missing in half of the rules we survey; moreover, when the Why is present, it is more likely to have quality issues than the What and the Fix.

翻译：自动静态分析工具（ASATs）被软件开发人员广泛用于推广和实施编码规范。然而，尽管文档对于初步了解编码规范至关重要，我们对ASATs的文档却知之甚少。本文通过以下贡献阐明了这一问题。首先，我们分析了针对多种编程语言的16个ASAT工具中超过100条规则的文档，并提炼出文档目的的分类——触发规则的原因、规则的重要性以及问题修复方法——及其内容类型。随后，我们开展了一项调查，以评估文档在其目标及内容类型方面的有效性。我们指出了ASAT文档的改进空间。特别地，我们发现所调查的规则中有一半缺少"为什么"这一目的说明；此外，当包含"为什么"时，其出现质量问题的可能性比"是什么"和"修复方法"更高。