如何正确记录python枚举元素？ [英] How do I properly document python enum elements?

问题描述

我知道我可以像其他任何类一样将Python docstring添加到枚举类型。但是，如何向该类型的元素添加文档？

I understand that I can add a Python docstring to an enum type as I would any other class. But how do I add documentation to an element of that type?

据我所知，存在三种可能性：

As far as I can see there are three possibilities:

class MyEnum(Enum):
    """
    This is my enum type.
    """

    """
    Variant 1
    """
    a = 0,  
    b = 1, # variant 2
    c = 2, """ variant 3 """

但是它们中的任何一个都不能真正连续地工作。
如果我在任何变体中调用 print（inspect.getdoc（MyEnum.a）），则 MyEnum 类型（这是我的枚举类型）。 Pycharm可以在其快速文档预览中显示变体3，但包含引号和超出列换行符的较长注释将无法正确显示。

But none of them really work consistently. If I call print(inspect.getdoc(MyEnum.a)) in any of the variants, the docstring of the MyEnum type is returned ('This is my enum type'). Pycharm can show variant 3 in its Quick Documentation preview, but includes the quotes and longer comments that exceed the column wrap will not be shown correctly.

是否存在首选方法或如何记录Python枚举元素的惯例？

Is there a preferred way or convention on how to document Python enum elements?

推荐答案

如果值本身并不重要，请参见如何将文档字符串放在枚举上？。如果值很重要，则可以自定义答案或使用 aenum ¹ 库：

If the values themselves are not important, see How do I put docstrings on Enums?. If the values are important you can either customize that answer or use the aenum¹ library:

from aenum import Enum

class MyEnum(Enum):
    _init_ = 'value __doc__'
    a = 0, 'docstring for a'
    b = 1, 'another for b'
    c = 2, 'and one for c as well'

会导致：

>>> MyEnum.b.value
1
>>> MyEnum.b.__doc__
'another for b'

但是，我不知道哪个，如果有的话，IDE支持使用Enum成员文档字符串。

However, I do not know which, if any, IDEs support using Enum member doc strings.

¹ 披露：我是 Python stdlib 枚举 ， enum34 移植，和高级枚举（ aenum ）库

¹ Disclosure: I am the author of the Python stdlib Enum, the enum34 backport, and the Advanced Enumeration (aenum) library.

这篇关于如何正确记录python枚举元素？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！