Это плохая практика, чтобы динамически генерировать документацию в строках документации - PullRequest
Новая
       26

Это плохая практика, чтобы динамически генерировать документацию в строках документации

1 голос
/ 02 мая 2019

Скажем, у меня есть класс с функциями: 

class Foo:
    def one():
        return 1
    def two():
        return 2
    def three():
        return 3
    def four():
        return 4

Если бы я хотел добавить строку документации (__doc__) к Foo, которая показывает все функции, которые я мог бы написать каждому методу индивидуально: 

class Foo:
    """
    one()
    two()
    three()
    four()"""

Но он также может генерироваться динамически, который создается во время выполнения: 

class Foo:
    def one():
        return 1
    def two():
        return 2
    def three():
        return 3
    def four():
        return 4

Foo.__doc__ = '()\n'.join(dir(Foo)) # __doc__ automatically list all methods with Foo (private and non private)

Это также может иметь другое применение.Например, запуск примеров реально используемых функций.

Это меньше работы для документирования больших модулей, но это означает, что производительность __doc__ будет снижена (так как это вряд ли когда-либо используется в готовых продуктах Iне вижу в этом проблемы) и больше не является константной строкой.

Это считается плохой практикой?

...