Atualmente, estou começando com Python e tenho uma sólida experiência em PHP e, em PHP, adquiri o hábito de usar javadoc
como modelo de documentação.
Eu queria saber se javadoc
tem o seu lugar como docstring
documentaçã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)
python
documentation
javadoc
docstring
JF Dion
fonte
fonte
Respostas:
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:
Ou estendido com informações de tipo:
fonte
Replace template place holder with values.
vez dereplaces template place holder with values
- Observe a frase, maiúscula no início e ponto final (.) No final.sphinx.ext.napoleon
extensão.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 ):
Exemplo retirado da documentação napoleana vinculada acima.
Um exemplo abrangente de todos os tipos de documentos aqui .
fonte
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
fonte
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.
fonte