問題描述

在twisted的源代碼中，很多文檔字符串包含這樣的格式:L{xxx}或C{xxx}或以'@'開頭的行，它們的含義是什么?

In twisted's sourcecode, many docstrings contain formats like this: L{xxx} or C{xxx} or a line begin with an '@', what's their meanings?

例如，在twisted/internet/interfaces.py中:

for example, in twisted/internet/interfaces.py:

def registerProducer(producer, streaming):
    """
    Register to receive data from a producer.
    ...
    For L{IPullProducer} providers, C{resumeProducing} will be called once
    each time data is required.
    ...
    @type producer: L{IProducer} provider
    ...
    @return: C{None}
    """

L{IPullProducer} , C{resumeProducing} , @type producer ?

順便問一下，這些格式是標準 python 文檔字符串格式的一部分嗎?如果是這樣，我應該參考哪里?謝謝:)

By the way, are these formats a part of standard python docstring formats? If so, where should I refer to? Thanks :)

推薦答案

Twisted 使用的文檔格式是 Epytext，記錄在 epydoc.sourceforge.net 上.

The documentation format used by Twisted is Epytext, which is documented on epydoc.sourceforge.net.

L{} 表示鏈接"(即這是一個 Python 標識符，請鏈接到它") C{} 表示代碼"(即 hello C{foo} bar 的格式應類似于hello foo bar").I{} 僅表示斜體".您可以在 epytext 文檔中看到更多字段.

L{} means "link" (i.e. "this is a Python identifier, please link to it") C{} means "code" (i.e. hello C{foo} bar should be formatted like "hello foo bar"). I{} just means "in italics". You can see more fields in the epytext documentation.

Twisted 項目使用 pydoctor 生成其文檔，使用像 pydoctor --add-package 這樣的調用扭曲.它還有更多內容，可以生成指向 Twisted 所依賴的其他幾個項目的鏈接，但如果你想向 Twisted 貢獻文檔字符串，你可以使用它來獲得一個想法.您也可以使用 epydoc 本身生成文檔，使用 epydoc twisted，但 epydoc 不了解 Zope 接口，因此不會自動將類鏈接到它們實現的接口.

The Twisted project generates its documentation with pydoctor, using an invocation like pydoctor --add-package twisted. There's a little more to it, to generate links to a couple of other projects that Twisted relies upon, but you can use that to get an idea if you want to contribute docstrings to Twisted. You can also generate the documentation with epydoc itself, using epydoc twisted, but epydoc doesn't know about Zope Interface and so won't automatically link classes to the interfaces that they implement.

為每個版本生成的 API 文檔發布在 twistedmatrix.com，您可以在那里瀏覽它.

The generated API documentation for each release is published on twistedmatrix.com, and you can browse it there.

這篇關于扭曲的文檔字符串中這些格式的含義是什么?的文章就介紹到這了，希望我們推薦的答案對大家有所幫助，也希望大家多多支持html5模板網！