Docstring
În programare, un docstring este un șir literal inserat în codul sursă care are funcția, ca un comentariu , de a documenta o porțiune de cod. Spre deosebire de comentarii, în text simplu sau cu formatare specială, cum ar fi javadoc sau doxygen , care sunt ignorate de compilator sau de parserul interpretor, docstring-urile sunt păstrate și sunt disponibile la runtime, simplificând inspecția codului și oferind ajutor sau metadate în timpul execuției.
Limbile care acceptă docstrings includ Python , Lisp , Elixir și Clojure . [1]
Exemple
Elixir
Docstring-urile sunt utilizate în Elixir pentru documentare, iar limbajul de markup folosit ca standard de facto este markdown :
defmodule MyModule do
@moduledoc "" "
Documentația formularului, cu reducere ** de formatare **.
"" "
@doc "Bună ziua"
def lume face
"Lume"
Sfârșit
Sfârșit
Lisp
În Lisp, docstrings sunt numite șiruri de documentare . Standardul Common Lisp afirmă că implementările pot ignora în mod liber docstrings. Când sunt păstrate, pot fi inspectate și editate folosind funcția DOCUMENTARE. [2]
( defun foo () "acesta este un șir de documente" zero )
( documentare # funcția ' foo ' ) => "acesta este un șir de documente"
Piton
Docstring-urile din Python sunt folosite pentru a documenta codul și sunt inserate ca prima declarație în urma definiției funcțiilor, metodelor, modulelor și claselor, în timp ce, dacă sunt inserate în altă parte, sunt ignorate. Docstring-urile sunt cuprinse între ghilimele duble triple și pot conține pauze de linie. Docstring-urile pot fi accesate prin intermediul atributului __doc__ al unui obiect. Liniile directoare privind utilizarea șirurilor de documente sunt colectate în PEP 257 ( Propunere de îmbunătățire Python ), la nivel de informații . Dacă șirul de documente este pe o singură linie, este recomandat să aveți ghilimelele de deschidere și de închidere pe aceeași linie, în timp ce dacă este pe mai multe linii, se recomandă să aveți un scurt pe aceeași linie ca ghilimelele de deschidere, urmat de detalii după un salt de linie și ghilimelele de închidere pe o nouă linie. [3]
"" "program.py
Acest șir de documente de la începutul fișierului este recunoscut.
"" "
clasa MyClass ( obiect ):
"" "Docstring al clasei.
Detalii despre clasă.
"" "
def my_method ( self ):
"" "Metoda docstring." ""
def my_function ():
"" "Funcția docstring." ""
Docstring-urile pot fi accesate într-o sesiune de interpret interactiv:
>>> import mymodule
>>> ajutor ( mymodule )
program . py
Acest șir de documente la „începutul fișierului este recunoscut.
>>> ajutor ( mymodule . MyClass )
Docstring al clasei.
Detalii despre clasă.
>>> ajutor ( mymodule . MyClass . my_method )
Docstring al metodei.
>>> ajutor ( mymodule . my_function )
Docstring al funcției.
>>>
Docstring-ul unui script trebuie să poată fi utilizat ca mesaj către utilizator, documentând în detaliu utilizarea acestuia, parametrii și sintaxa. Un șir de documente al unui modul listează de obicei clasele, excepțiile și funcțiile exportate din modul, cu o linie de explicație pentru fiecare dintre componente. De obicei, un pachet raportează module și subpachete exportate din pachet. Docstring-ul unei metode este de obicei o propoziție dintr-o singură perioadă care raportează efectul într-un mod concis („Fa x ”, „Returnează y ”), fără a intra în descriere, sau poate fi un docstring multiliniu care după o linie de descriere sumar raportează detaliile tuturor parametrilor (chiar și opționali), valorile returnate, efectele secundare , excepțiile și restricțiile de utilizare. Docstring-ul unei clase rezumă comportamentul său și listează de obicei metodele și atributele, orice interfețe pe subclasă. Constructorul și metodele ar trebui să fie documentate în detaliu în documentele lor.
Formate
PEP 257 menționat anterior nu specifică un anumit format pentru documentare. Sunt utilizate în mod obișnuit diverse formate, în funcție de convenții sau instrumente de generare automată a documentației adoptate în proiectele care urmează să fie documentate. Iată câteva exemple de docstring pentru a documenta o funcție cu unele dintre principalele formate utilizate în mod obișnuit.
Epydoc acceptă un format împrumutat de la javadoc : [4]
"" "Scurt
Descriere...
@param p1: descrierea primului parametru p1
@param p2: descrierea celui de-al doilea parametru p2
@return: descrierea valorii returnate a funcției
@raise Exception: descrierea excepției aruncate
"" "
Epydoc și Sphinx acceptă formatul reStructuredText (reST): [5]
"" "Scurt
Descriere...
: param p1: descrierea primului parametru p1
: param p2: descrierea celui de-al doilea parametru p2
: returnează: descrierea valorii returnate a funcției
: ridică Excepție: descrierea excepției aruncate
"" "
Convențiile stilistice Google specifică formatul lor, utilizat în proiectele Google Python și destul de răspândit în altă parte, care poate fi citit și de Sphinx [6] :
"" "Scurt
Descriere...
Args:
p1: descrierea primului parametru p1
p2: descrierea celui de-al doilea parametru p2
Se intoarce:
Descrierea valorii returnate
Crește:
Excepție: descrierea excepției aruncate
"" "
NumPy are propriul format de docstring împrumutat din formatul Google, lizibil de Sphinx.
"" "Scurt
Descriere...
Parametrii
----------
p1: tip
descrierea primului parametru p1
p2: tip
descrierea celui de-al doilea parametru p2
p3: tip, opțional
descrierea celui de-al treilea parametru opțional p3
Se intoarce
-------
tip
descrierea tipului de returnare
Ridică
------
Excepție
descrierea excepției aruncate
"" "
Notă
- ^ Definiția funcției cu docstring în Clojure
- ^ Funcția DOCUMENTARE
- ^ PEP 257
- ^ Epydoc , la epydoc.sourceforge.net .
- ^ Sfinx , la sphinx-doc.org .
- ^ (EN) styleguide , pe styleguide. Adus la 17 octombrie 2019 .
Elemente conexe
linkuri externe
- Python Docstrings , la epydoc.sourceforge.net .
- Documentație în GNU Emacs Lisp , la linuxselfhelp.com . Adus la 18 aprilie 2015 (arhivat din original la 3 martie 2016) .
- Secțiunea despre șiruri de documente în documentația doxygen
