2012-06-17 699 views
9

Trong mã nguồn của xoắn, nhiều tài liệu có chứa các định dạng như sau: L {xxx} hoặc C {xxx} hoặc dòng bắt đầu bằng '@', ý nghĩa của chúng là gì?Ý nghĩa của các định dạng này trong docstring của xoắn là gì?

ví dụ, trong xoắn/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, nhà sản xuất @type?

Nhân tiện, các định dạng này có phải là một phần của định dạng chuỗi mã vạch python chuẩn không? Nếu vậy, tôi nên tham khảo ở đâu? Cảm ơn :)

Trả lời

11

Định dạng tài liệu được sử dụng bởi Twisted là Epytext, which is documented on epydoc.sourceforge.net.

L{} có nghĩa là "liên kết" (ví dụ: "đây là một định danh Python, xin vui lòng liên kết với nó") C{} có nghĩa là "mã" (ví dụ: hello C{foo} bar nên được định dạng như "hello foo bar"). I{} chỉ có nghĩa là "in nghiêng". Bạn có thể xem thêm các trường trong tài liệu epytext.

Dự án xoắn tạo tài liệu với pydoctor, sử dụng lời gọi như pydoctor --add-package twisted. Có nhiều hơn một chút cho nó, để tạo ra các liên kết đến một vài dự án khác mà Twisted dựa vào, nhưng bạn có thể sử dụng nó để có ý tưởng nếu bạn muốn đóng góp tài liệu cho Twisted. Bạn cũng có thể tạo tài liệu với chính epydoc, sử dụng epydoc twisted, nhưng epydoc không biết về Giao diện Zope và do đó sẽ không tự động liên kết các lớp với các giao diện mà chúng triển khai.

The generated API documentation for each release is published on twistedmatrix.com và bạn có thể duyệt ở đó.