Điều gì để đặt vào một chuỗi mô-đun python?

Question

Ok, vì vậy tôi đã đọc cả PEP 8 và PEP 257 và tôi đã viết rất nhiều tài liệu về các chức năng và lớp học, nhưng tôi không chắc chắn về những gì nên đi vào một chuỗi tài liệu mô-đun. Tôi đã tìm ra, ở mức tối thiểu, nó cần ghi lại các hàm và các lớp mà module xuất ra, nhưng tôi cũng đã thấy một vài mô-đun liệt kê tên tác giả, thông tin bản quyền, v.v. Có ai có ví dụ về cách một chuỗi docthon tốt nên được cấu trúc?

Answer 1

Hãy suy nghĩ về ai đó đang làm help(yourmodule) tại lời nhắc của thông dịch viên tương tác - họ làm gì muốn để biết? (Các phương pháp trích xuất và hiển thị thông tin khác tương đương với help về số lượng thông tin). Vì vậy, nếu bạn có trong x.py:

"""This module does blah blah.""" 

class Blah(object): 
    """This class does blah blah.""" 

thì:

>>> import x; help(x) 

show:

Help on module x: 

NAME 
    x - This module does blah blah. 

FILE 
    /tmp/x.py 

CLASSES 
    __builtin__.object 
     Blah 

    class Blah(__builtin__.object) 
    | This class does blah blah. 
    | 
    | Data and other attributes defined here: 
    | 
    | __dict__ = <dictproxy object> 
    |  dictionary for instance variables (if defined) 
    | 
    | __weakref__ = <attribute '__weakref__' of 'Blah' objects> 
    |  list of weak references to the object (if defined) 

Như bạn thấy, các thông tin chi tiết về các lớp học (và chức năng quá, mặc dù tôi m không hiển thị một ở đây) đã được bao gồm trong các tài liệu của các thành phần đó; docstring riêng của mô-đun nên mô tả chúng rất tổng quát (nếu ở tất cả) và tập trung vào một bản tóm tắt ngắn gọn về những gì mà toàn bộ mô-đun có thể làm cho bạn, lý tưởng với một số ví dụ về doctested (giống như các hàm và lớp học lý tưởng). theit docstrings).

Tôi không thấy cách siêu dữ liệu như tên tác giả và bản quyền/giấy phép giúp người dùng của mô-đun - nó có thể được đưa vào nhận xét, vì nó có thể giúp ai đó xem xét có sử dụng lại hay sửa đổi mô-đun hay không.

Answer 2

Để trích dẫn specifications:

Các docstring của một kịch bản (một chương trình độc lập) nên được sử dụng như thông điệp của mình "sử dụng", in khi kịch bản được gọi với không chính xác hoặc thiếu đối số (hoặc có thể với tùy chọn "-h", cho "trợ giúp"). Một docstring như vậy nên ghi lại cú pháp của hàm và cú pháp dòng lệnh, các biến môi trường và các tệp. Thông báo sử dụng có thể khá phức tạp (một số màn hình đầy đủ) và phải đủ để người dùng mới sử dụng lệnh đúng cách, cũng như tham chiếu nhanh đầy đủ đến tất cả các tùy chọn và đối số cho người dùng tinh vi.

Chuỗi tài liệu cho mô-đun thường liệt kê các lớp, ngoại lệ và chức năng (và bất kỳ đối tượng nào khác) được mô-đun xuất, với bản tóm tắt một dòng của mỗi mô-đun.) Các chuỗi tổng hợp cho một gói (tức là, docstring của mô-đun __init__.py của gói) cũng nên liệt kê các mô đun và các gói con được xuất khẩu bởi gói.

Chuỗi tài liệu cho số lớp nên tóm tắt hành vi của nó và liệt kê các phương pháp công khai và biến mẫu. Nếu lớp được dự định là lớp con và có giao diện bổ sung cho các lớp con, giao diện này sẽ được liệt kê riêng (trong chuỗi tài liệu). Lớp khởi tạo nên được ghi lại trong docstring cho phương thức __init__ của nó. Các phương thức riêng lẻ nên được ghi lại bằng docstring của riêng chúng.

Các docstring của một chức năng hoặc phương pháp là một cụm từ kết thúc bằng một dấu chấm. Nó quy định hiệu ứng của hàm hoặc phương thức như một lệnh ("Thực hiện điều này", "Trả về"), không phải là mô tả; ví dụ. không viết "Trả về tên đường dẫn ...". Một multiline-docstring cho một hàm hoặc phương thức nên tóm tắt hành vi của nó và ghi lại các đối số của nó, trả về giá trị, tác dụng phụ, ngoại lệ, và hạn chế khi nó có thể được gọi (tất cả nếu có). Đối số tùy chọn phải được chỉ định. Nó nên được ghi lại liệu các đối số từ khóa có phải là một phần của giao diện hay không.