Các tài liệu Python là các chuỗi ký tự xuất hiện ngay sau định nghĩa của hàm, phương thức, lớp hoặc mô-đun. Hãy lấy một ví dụ
ví dụ 1. tài liệu
def square[n]:
'''Takes in a number n, returns the square of n'''
return n**2Ở đây, chuỗi ký tự
'''Takes in a number n, returns the square of n'''
Bên trong ba dấu ngoặc kép là chuỗi tài liệu của hàm
'''Takes in a number n, returns the square of n'''8 khi nó xuất hiện ngay sau định nghĩa của nó
Ghi chú. Chúng tôi cũng có thể sử dụng ba trích dẫn
'''Takes in a number n, returns the square of n'''9 để tạo chuỗi tài liệu
Bình luận Python
Chú thích là phần mô tả giúp người lập trình hiểu rõ hơn về mục đích và chức năng của chương trình. Chúng hoàn toàn bị bỏ qua bởi trình thông dịch Python
Trong Python, chúng tôi sử dụng ký hiệu băm
# Program to print "Hello World"
print["Hello World"] # Program to print "Hello World"
print["Hello World"] Nhận xét Python bằng cách sử dụng chuỗi
Nếu chúng ta không gán chuỗi cho bất kỳ biến nào, chúng sẽ đóng vai trò là nhận xét. Ví dụ,
"I am a single-line comment"
'''
I am a
multi-line comment!
'''
print["Hello World"]Ghi chú. Chúng tôi sử dụng ba dấu ngoặc kép cho chuỗi nhiều dòng
tài liệu Python
Như đã đề cập ở trên, chuỗi tài liệu Python là chuỗi được sử dụng ngay sau định nghĩa của hàm, phương thức, lớp hoặc mô-đun [như trong Ví dụ 1]. Chúng được sử dụng để ghi lại mã của chúng tôi
Chúng ta có thể truy cập các chuỗi tài liệu này bằng thuộc tính
# Program to print "Hello World"
print["Hello World"] Thuộc tính __doc__ của Python
Bất cứ khi nào các chuỗi ký tự xuất hiện ngay sau định nghĩa của hàm, mô-đun, lớp hoặc phương thức, chúng sẽ được liên kết với đối tượng dưới dạng thuộc tính
# Program to print "Hello World"
print["Hello World"] ví dụ 2. In chuỗi tài liệu
def square[n]:
'''Takes in a number n, returns the square of n'''
return n**2
print[square.__doc__]đầu ra
'''Takes in a number n, returns the square of n'''0
Tại đây, tài liệu về hàm
'''Takes in a number n, returns the square of n'''8 của chúng ta có thể được truy cập bằng thuộc tính
# Program to print "Hello World"
print["Hello World"] Bây giờ, hãy xem các chuỗi tài liệu cho hàm tích hợp sẵn
# Program to print "Hello World"
print["Hello World"] ví dụ 3. Tài liệu cho chức năng print[] tích hợp
'''Takes in a number n, returns the square of n'''4
đầu ra
'''Takes in a number n, returns the square of n'''5
Ở đây, chúng ta có thể thấy rằng tài liệu của hàm
# Program to print "Hello World"
print["Hello World"] # Program to print "Hello World"
print["Hello World"] Tài liệu một dòng trong Python
Các tài liệu dòng đơn là các tài liệu nằm gọn trong một dòng
Các quy ước tiêu chuẩn để viết các tài liệu một dòng
- Mặc dù chúng là dòng đơn, chúng tôi vẫn sử dụng dấu ngoặc kép xung quanh các tài liệu này vì chúng có thể được mở rộng dễ dàng sau này
- Dấu ngoặc kép đóng cùng dòng với dấu ngoặc kép mở
- Không có dòng trống nào trước hoặc sau chuỗi tài liệu
- Chúng không nên mang tính mô tả, thay vào đó chúng phải tuân theo cấu trúc "Làm cái này, trả lại cái kia" kết thúc bằng dấu chấm.
Hãy lấy một ví dụ
Ví dụ 4. Viết chuỗi tài liệu một dòng cho một hàm
'''Takes in a number n, returns the square of n'''8
Tài liệu nhiều dòng trong Python
Chuỗi tài liệu nhiều dòng bao gồm một dòng tóm tắt giống như chuỗi tài liệu một dòng, theo sau là một dòng trống, tiếp theo là mô tả phức tạp hơn
Tài liệu PEP 257 cung cấp các quy ước tiêu chuẩn để viết các chuỗi tài liệu nhiều dòng cho các đối tượng khác nhau
Một số đã được liệt kê dưới đây
1. Tài liệu cho các mô-đun Python
- Các chuỗi tài liệu cho Mô-đun Python phải liệt kê tất cả các lớp, hàm, đối tượng và ngoại lệ có sẵn được nhập khi mô-đun được nhập
- Họ cũng nên có một bản tóm tắt một dòng cho mỗi mục
Chúng được viết ở đầu tệp Python
Hãy xem các tài liệu về mô-đun dựng sẵn trong Python có tên là
# Program to print "Hello World"
print["Hello World"] Ví dụ 4. Docstrings của mô-đun Python
'''Takes in a number n, returns the square of n'''0
đầu ra
'''Takes in a number n, returns the square of n'''0
Ở đây, chúng ta có thể thấy rằng chuỗi tài liệu được viết ở đầu pickle. tệp mô-đun py có thể được truy cập dưới dạng chuỗi tài liệu của nó
2. Tài liệu cho hàm Python
- Chuỗi tài liệu cho một hàm hoặc phương thức sẽ tóm tắt hành vi của nó và ghi lại các đối số và giá trị trả về của nó
- Nó cũng nên liệt kê tất cả các ngoại lệ có thể được nêu ra và các đối số tùy chọn khác
Ví dụ 5. Tài liệu cho các chức năng Python
'''Takes in a number n, returns the square of n'''1
đầu ra
'''Takes in a number n, returns the square of n'''2
Như bạn có thể thấy, chúng tôi đã bao gồm một mô tả ngắn về chức năng của hàm, tham số mà hàm nhận vào và giá trị mà hàm trả về. Chuỗi ký tự được nhúng vào hàm
# Program to print "Hello World"
print["Hello World"] # Program to print "Hello World"
print["Hello World"] 3. Tài liệu cho các lớp Python
- Các chuỗi tài liệu cho các lớp nên tóm tắt hành vi của nó và liệt kê các phương thức công khai và các biến thể hiện
- Mỗi lớp con, hàm tạo và phương thức phải có chuỗi tài liệu riêng
Ví dụ 6. Tài liệu cho lớp Python
Giả sử chúng ta có một Người. py với đoạn mã sau
'''Takes in a number n, returns the square of n'''3
Ở đây, chúng ta có thể sử dụng đoạn mã sau để chỉ truy cập các tài liệu của lớp Person
'''Takes in a number n, returns the square of n'''4
đầu ra
'''Takes in a number n, returns the square of n'''5
Sử dụng hàm help[] cho Docstrings
Chúng ta cũng có thể sử dụng hàm
"I am a single-line comment"
'''
I am a
multi-line comment!
'''
print["Hello World"]Ví dụ 7. Đọc Docstrings với hàm help[]
Chúng ta có thể sử dụng hàm
"I am a single-line comment"
'''
I am a
multi-line comment!
'''
print["Hello World"]"I am a single-line comment"
'''
I am a
multi-line comment!
'''
print["Hello World"]'''Takes in a number n, returns the square of n'''6
đầu ra
'''Takes in a number n, returns the square of n'''7
Ở đây, chúng ta có thể thấy rằng hàm
"I am a single-line comment"
'''
I am a
multi-line comment!
'''
print["Hello World"]"I am a single-line comment"
'''
I am a
multi-line comment!
'''
print["Hello World"]4. Tài liệu cho tập lệnh Python
- Các chuỗi tài liệu cho tập lệnh Python sẽ ghi lại các chức năng của tập lệnh và cú pháp dòng lệnh dưới dạng một thông báo có thể sử dụng được
- Nó sẽ phục vụ như một tham chiếu nhanh đến tất cả các chức năng và đối số
5. Tài liệu cho các gói Python
Các tài liệu cho gói Python được viết trong __init__ của gói. tập tin py
- Nó phải chứa tất cả các mô-đun và gói con có sẵn được xuất bởi gói
Định dạng chuỗi tài liệu
Chúng tôi có thể viết chuỗi tài liệu ở nhiều định dạng như định dạng văn bản được cấu trúc lại [reST], định dạng Google hoặc định dạng tài liệu NumPy. Để tìm hiểu thêm, hãy truy cập Định dạng chuỗi tài liệu phổ biến
Chúng tôi cũng có thể tạo tài liệu từ chuỗi tài liệu bằng các công cụ như Sphinx. Để tìm hiểu thêm, hãy truy cập Tài liệu Nhân sư Chính thức