Usando o javadoc para documentação do Python [fechado]

162

Atualmente, estou começando com Python e tenho uma sólida experiência em PHP e, em PHP, adquiri o hábito de usar javadoccomo modelo de documentação.

Eu queria saber se javadoctem o seu lugar como docstringdocumentação em Python. Quais são as convenções estabelecidas e / ou guildelines oficiais aqui?

Por exemplo, algo assim é muito elaborado para caber na mentalidade de Python ou devo tentar ser o mais conciso possível?

"""
replaces template place holder with values

@param string timestamp     formatted date to display
@param string priority      priority number
@param string priority_name priority name
@param string message       message to display

@return string formatted string
"""

E se eu sou um pouco exaustivo, devo usar algo assim (onde a maior parte da documentação não é impressa através do __doc__método)?

# replaces template place holder with values
#    
# @param string timestamp     formatted date to display
# @param string priority      priority number
# @param string priority_name priority name
# @param string message       message to display
#    
# @return string formatted string

def format(self, timestamp = '', priority = '', priority_name = '', message = ''):
    """
    replaces template place holder with values
    """
    values = {'%timestamp%' : timestamp,
              '%priorityName%' : priority_name,
              '%priority%' : priority,
              '%message%' : message}

    return self.__pattern.format(**values)
JF Dion
fonte
6
Há também muitas outras respostas para isso na pergunta anterior, da qual é uma duplicata.
AlexDupuy

Respostas:

227

Dê uma olhada no formato reStructuredText (também conhecido como "reST"), que é um formato de marcação de texto sem formatação / documentação e provavelmente o mais popular no mundo Python. E você certamente deve olhar para o Sphinx , uma ferramenta para gerar documentação a partir do reStructuredText (usado para, por exemplo, a própria documentação do Python). O Sphinx inclui a possibilidade de extrair a documentação dos documentos no seu código (consulte sphinx.ext.autodoc ) e reconhece as listas de campos reST seguindo certas convenções. Isso provavelmente se tornou (ou está se tornando) a maneira mais popular de fazer isso.

Seu exemplo pode ter a seguinte aparência:

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:param priority: priority number
:param priority_name: priority name
:param message: message to display
:returns: formatted string
"""

Ou estendido com informações de tipo:

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:type timestamp: str or unicode
:param priority: priority number
:type priority: str or unicode
:param priority_name: priority name
:type priority_name: str or unicode
:param message: message to display
:type message: str or unicode
:returns: formatted string
:rtype: str or unicode
"""
Steven
fonte
7
o que você faz se precisar quebrar uma linha para uma descrição longa? Como isso seria?
Skylar Saveland
6
Consulte a referência reStructuredText e as listas de campos em particular: docutils.sourceforge.net/docs/ref/rst/…
Steven
6
Observe que a maneira como as frases aqui não estão em conformidade com o PEP 257 . Deve estar em Replace template place holder with values.vez de replaces template place holder with values- Observe a frase, maiúscula no início e ponto final (.) No final.
kratenko
1
Desde a versão 1.3, o Sphinx também suporta um formato um pouco melhor através da sphinx.ext.napoleonextensão.
Petri
3
Alguém poderia me indicar a melhor documentação que especifica esses documentos especiais como ": param ____:" e ": Returns:"? Esse documento parece bastante difícil de encontrar no momento.
22416 krumpelstiltskin
75

Siga o Guia de estilos do Google Python . Observe que o Sphinx também pode analisar esse formato usando a extensão Napolean , que será fornecida com o Sphinx 1.3 (isso também é compatível com o PEP257 ):

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

Exemplo retirado da documentação napoleana vinculada acima.

Um exemplo abrangente de todos os tipos de documentos aqui .

confused00
fonte
20
para todos os seres humanos lá fora que lêem docstrings
Waylon Flinn
1
Atualizado o link do Google Python Style Guide
confused00
@ confused00 como posso documentar que meu método está retornando uma matriz de objetos?
Cito
1
Agora eu estou confuso ! args ou params? stackoverflow.com/questions/1788923/parameter-vs-argument
shuva
25

O padrão para cadeias de documentação do python é descrito na Proposta de Aprimoramento do Python 257 .

O comentário apropriado para o seu método seria algo como

def format(...):
    """Return timestamp string with place holders replaced with values.

    Keyword arguments:
    timestamp     -- the format string (default '')
    priority      -- priority number (default '')
    priority_name -- priority name (default '')
    message       -- message to display (default '')
    """
srgerg
fonte
17
O PEP257 não diz nada sobre a formatação real da parte do argumento. Apenas afirma que deve ser escrito e dá um exemplo. Mas este é apenas um exemplo. Portanto, eu recomendaria definitivamente o uso da convenção Sphinx, pois você não quebra o PEP257 e usa uma formatação que pode ser analisada pela esfinge.
vaab
7
Exceto que a primeira documentação apresentada acima é feia e possui muitas informações redundantes para humanos. Eu prefiro usar uma convenção que faz o meu código fonte agradável de ler sem ser analisado primeiro
confused00
1

Dê uma olhada em Documentando Python , uma página "direcionada a autores e autores potenciais de documentação para Python".

Em resumo, reStructuredText é o que é usado para documentar o próprio Python. O guia do desenvolvedor contém um iniciador reST, um guia de estilo e conselhos gerais para escrever uma boa documentação.

David Cain
fonte