Chuỗi tài liệu Python [or docstrings] tạo điều kiện liên kết tài liệu với các mô-đun, hàm, lớp và phương thức Python. Chuỗi tài liệu của một đối tượng được định nghĩa bằng cách bao gồm một chuỗi hằng làm câu lệnh đầu tiên trong định nghĩa của đối tượng. Nó chỉ được xác định trong mã nguồn, được sử dụng, giống như một nhận xét, để ghi lại một đoạn mã cụ thể
Nội dung chính Hiển thị
- Constructor of Docstring in Python
- Ví dụ về Docstring
- Cách sử dụng Docstrings trong Python
- Khai báo Docstrings trong Python
- Truy cập Docstrings
- Ví dụ. Sử dụng dấu ngoặc kép
- Ví dụ. Sử dụng ba dấu ngoặc kép
- Đánh dấu trong Docstrings
- Docstring one line in Python
- Docstring nhiều dòng trong Python
- Sự khác biệt giữa nhận xét Python và docstrings
Không giống như các bình luận bình luận mã nguồn thông thường, chuỗi tài liệu phải mô tả chức năng hoạt động chứ không phải như thế nào. Tất cả các hàm phải có một Docstring, Điều này cho phép chương trình kiểm tra các nhận xét này tại thời điểm chạy, ví dụ như một hệ thống trợ giúp tương tác hoặc dưới dạng siêu dữ liệu
>>>Xem thêm. Không gian tên trong Python- Tìm hiểu về không gian tên trong Python
Ví dụ về Docstring trong Python
Constructor of Docstring in Python
- Dòng chuỗi doc phải bắt đầu bằng chữ hoa và kết thúc bằng dấu chấm
- First line should be a short description
- Nếu có nhiều dòng hơn trong chuỗi tài liệu, dòng thứ hai phải để trống, ngăn cách trực tiếp quan phần bản tóm tắt với phần còn lại của mô tả
- Các dòng sau nên là một hoặc nhiều đoạn văn bản mô tả các quy ước gọi của đối tượng, các tác dụng phụ của nó,
Ví dụ về Docstring
hình vuông chắc chắn [n]
'''Lấy vào một số n, trả về bình phương của n'''
trả lại n**2
Cách sử dụng Docstrings trong Python
Khai báo Docstrings trong Python
Các chuỗi tài liệu được khai báo bằng cách sử dụng "" dấu trích dẫn ba "" hoặc "" "dấu trích ba" "" ngay bên dưới khai báo lớp, phương thức hoặc hàm. Tất cả các chức năng phải có một chuỗi tài liệu
Truy cập Docstrings
Có thể truy cập chuỗi tài liệu bằng phương thức __doc__ của đối tượng hoặc sử dụng hàm trợ giúp
Các ví dụ dưới đây trình bày cách khai báo và truy cập một chuỗi tài liệu
Ví dụ. Sử dụng dấu ngoặc kép
def my_function[]
'''Thể hiện ba dấu ngoặc kép
docstrings và không có gì thực sự. '''
trở lại Không có
print["Dùng __doc__. "]
in [my_function. __doc__]
print["Sử dụng trợ giúp. "]
trợ giúp [my_function]
đầu ra
Sử dụng __doc__
Thể hiện ba dấu ngoặc kép
docstrings và không có gì thực sự
Sử dụng trợ giúp
Trợ giúp về chức năng my_function trong mô-đun __main__
my_function[]
Thể hiện ba dấu ngoặc kép
docstrings và không có gì thực sự
Ví dụ. Sử dụng ba dấu ngoặc kép
def my_function[].
"""Thể hiện ba dấu ngoặc kép
docstrings và không có gì thực sự. """
trở lại Không có
print["Dùng __doc__. "]
in [my_function. __doc__]
print["Sử dụng trợ giúp. "]
trợ giúp [my_function]
đầu ra
Sử dụng __doc__
Thể hiện ba dấu ngoặc kép
docstrings và không có gì thực sự
Sử dụng trợ giúp
Trợ giúp về chức năng my_function trong mô-đun __main__
my_function[]
Thể hiện ba dấu ngoặc kép
docstrings và không có gì thực sự
>>>Tham khảo. Key learning set Python
Đánh dấu trong Docstrings
Toàn bộ Docstring trong Python được nhận dấu ngoặc kép giống như các dấu ngoặc kép ở dòng đầu tiên của nó. Các công cụ xử lý Docstring sẽ loại bỏ một lượng thụt lề hệ thống nhất từ dòng thứ hai và các dòng tiếp theo của chuỗi tài liệu, bằng với mức thụt lề tối thiểu của tất cả các dòng không trống sau dòng đầu tiên. Bất kỳ dấu ngoặc kép nào trong dòng đầu tiên của chuỗi tài liệu [tức là đến dòng đầu tiên mới] là không đáng kể và sẽ bị loại bỏ. Shut lề tương đối của các dòng sau đó trong chuỗi docstring được giữ lại
Docstring one line in Python
Một dòng tài liệu là một chuỗi tài liệu nằm trong một dòng. Chúng được sử dụng trong các trường hợp hiển thị. Như trong ví dụ dưới đây, dấu ngoặc kép đóng và mở đều nằm trên cùng một dòng.
Ví dụ. sức mạnh def[a, b]
"""Trả về arg1 được nâng lên lũy thừa arg2. """
trả lại một ** b
in [sức mạnh. __doc__]
Kết quả
Trả về arg1 được nâng lên thành sức mạnh arg2
Docstring nhiều dòng trong Python
Docstring nhiều dòng bao gồm một biên bản tương tự như Docstring một dòng, theo sau là một dòng trống, tiếp theo là mô tả chi tiết hơn. Dòng tóm tắt có thể nằm trên cùng một dòng với phần mở đầu hoặc dòng tiếp theo
Ví dụ dưới đây cho thấy một Docstring nhiều dòng
def my_function[arg1]
"""
Dòng tóm tắt
Mô tả chức năng mở rộng
Thông số
arg1 [int]. Mô tả của arg1
trả lại
int. Mô tả giá trị trả về
"""
trở lại arg1
in [my_function. __doc__]
Sự khác biệt giữa nhận xét Python và docstrings
Bình luận Python là thông tin hữu ích mà nhà phát triển cung cấp để giúp người đọc hiểu mã nguồn. Nó giải thích logic hoặc một phần của nó được sử dụng trong mã hóa. Nó được viết bằng cách sử dụng ký hiệu #.
Trong khi Docstrings trong Python cung cấp một cách thuận tiện để liên kết tài liệu với các mô-đun, hàm, lớp và phương thức Python
Kết luận. Docstring là một thành phần cần thiết cho quá trình lập trình trong Python. Bài viết trên đã giúp bạn tìm hiểu về Docstring, các khái niệm và cách sử dụng Docstring trong Python. Muốn truy cập Python và các ngôn ngữ lập trình khác, tìm hiểu ngay các khóa học lập trình tại T3H bạn nhé