Add more comment-formats for documentation

byaka commented 6 years ago

From @byaka on August 13, 2016 13:48

Сейчас обрабатывается только один формат комментариев-описаний. Нужно расширить или добавить другие, например в flask не все комментарии обработались корректно, часть данных из них потерялась.

Copied from original issue: devanonymous/docit#4

byaka commented 6 years ago

From @devanonymous on August 15, 2016 9:37

Имеется ввиду, что docit подхватывает коментарии только из двойных кавычек?

byaka commented 6 years ago

Нет, речь не об этом. Докстринг извлекается так

      # извлекаем общий комментарий
      if isModule(obj):
         docstr=strGet(inspect.getsource(obj), '"""\n', '\n"""') or ''
      else:
         docstr=inspect.getdoc(obj) or inspect.getcomments(obj) or ''

pydoc2api.py:152, для модуля действительно извлекается сейчас только по двойным ковычкам, для всего остального через питоновый инспект из байткода.

проблема в другом - PEP257 и сопутствующие документы не описывает конкретный формат каждой возможной секции (параметры, примеры, варнинги и т.д.), поэтому формат докстрингов отличается в разных проектах. docit сейчас парсит формат типа этого и этого. Этот формат покрывает многие проекты, но не все. Например есть еще такой формат, который тоже распостранен. Его docit парсить не умеет.

byaka / docit

Add more comment-formats for documentation #5