根据 PEP257 自动检查文档字符串样式的工具 [关闭]

Posted 2023-04-18

【中文标题】根据 PEP257 自动检查文档字符串样式的工具 [关闭]

【英文标题】：Tool for automatically check docstring style according to PEP257 [closed]

【发布时间】：2012-02-02 05:39:08

【问题描述】：

pep8 之类的工具可以检查源代码样式，但它们不检查文档字符串是否根据pep257、pep287 进行了格式设置。有这样的工具吗？

更新

我决定自己实现这样一个静态分析工具，见：

https://github.com/GreenSteam/pep257

目前，pep257 的大部分内容都已覆盖。 设计深受提到的pep8 工具的影响。

【参考方案1】：

我不知道任何用于 python 文档字符串的静态分析工具。实际上，我在开始使用 PyLint 后不久就开始构建一个，但很快就放弃了。

PyLint 有一个插件系统和一个文档字符串插件是可行的，如果你想把工作放入使 PEP 可执行。

PyLint“插件”被称为检查器，有两种形式：将源文件作为原始文本文档使用，以及将源文件作为 AST 使用。我从 AST 开始尝试。回想起来，这可能是一个错误。

这是我所拥有的：

class DocStringChecker(BaseChecker):
    """
    PyLint AST based checker to eval compliance with PEP 257-ish conventions.
    """
    __implements__ = IASTNGChecker

    name = 'doc_string_checker'
    priority = -1
    msgs = 'W9001': ('One line doc string on >1 lines',
                     ('Used when a short doc string is on multiple lines')),
            'W9002': ('Doc string does not end with "." period',
                     ('Used when a doc string does not end with a period')),
            'W9003': ('Not all args mentioned in doc string',
                     ('Used when not all arguments are in the doc string ')),
            'W9004': ('triple quotes',
                     ('Used when doc string does not use """')),
           
    options = ()

    def visit_function(self, node):
        if node.doc: self._check_doc_string(node)

    def visit_module(self, node):
        if node.doc: self._check_doc_string(node)

    def visit_class(self, node):
        if node.doc: self._check_doc_string(node)

    def _check_doc_string(self, node):
        self.one_line_one_one_line(node)
        self.has_period(node)
        self.all_args_in_doc(node)

    def one_line_one_one_line(self,node):
        """One line docs (len < 80) are on one line"""
        doc = node.doc
        if len(doc) > 80: return True
        elif sum(doc.find(nl) for nl in ('\n', '\r', '\n\r')) == -3: return True
        else:
            self.add_message('W9001', node=node, line=node.tolineno)

    def has_period(self,node):
        """Doc ends in a period"""
        if not node.doc.strip().endswith('.'):
            self.add_message('W9002', node=node, line=node.tolineno)

    def all_args_in_doc(self,node):
        """All function arguments are mentioned in doc"""
        if not hasattr(node, 'argnames'): return True
        for arg in node.argnames:
            if arg != 'self' and arg in node.doc: continue
            else: break
        else: return True
        self.add_message('W9003', node=node, line=node.tolineno)

    def triple_quotes(self,node): #This would need a raw checker to work b/c the AST doesn't use """
        """Doc string uses tripple quotes"""
        doc = node.doc.strip()
        if doc.endswith('"""') and doc.startswith('"""'): return True
        else: self.add_message('W9004', node=node, line=node.tolineno)


def register(linter):
    """required method to auto register this checker"""
    linter.register_checker(DocStringChecker(linter))

我记得这个系统没有很好的文档（过去一年可能发生了变化）。这至少给了你一些东西来开始使用/非常简单的代码来代替文档。

【参考方案2】：

我认为它不会针对任何 PEP 进行验证，但 Epydoc 会检查 docstrmap 中所有引用的参数和对象是否为有效参数和对象。