En programación , una docstring es una cadena literal especificada en el código fuente que se utiliza, como un comentario , para documentar un segmento específico de código. A diferencia de los comentarios de código fuente convencionales, o incluso de los comentarios con formato específico como docblocks , las docstrings no se eliminan del árbol de código fuente cuando se analiza y se conservan durante el tiempo de ejecución del programa. Esto permite al programador inspeccionar estos comentarios en tiempo de ejecución, por ejemplo, como un sistema de ayuda interactivo o como metadatos .
Los lenguajes que admiten cadenas de documentación incluyen Python , Lisp , Elixir , Clojure , [1] Gherkin , [2] Julia [3] y Haskell . [4]
La documentación se respalda a nivel de lenguaje, en forma de cadenas de documentación. Markdown es el lenguaje de marcado de facto de Elixir elegido para su uso en cadenas de documentación:
def module MyModule do @moduledoc """ Documentación para mi módulo. Con **formato**. """ @doc "Hola" def mundo do "Mundo" fin fin En Lisp, las cadenas de documentación se conocen como cadenas de documentación. El estándar Common Lisp establece que una implementación particular puede optar por descartar cadenas de documentación cuando lo desee, por cualquier motivo. Cuando se conservan, las cadenas de documentación se pueden ver y modificar mediante la función DOCUMENTATION. [5] Por ejemplo:
( defun foo () "hola" nil ) ( documentación #' función foo ' ) => "hola" La práctica común de documentar un objeto de código al principio de su definición se captura mediante la adición de la sintaxis docstring en el lenguaje Python.
La cadena de documentación de un objeto de código Python (un módulo, una clase o una función) es la primera declaración de ese objeto de código, inmediatamente después de la definición (la declaración 'def' o 'class'). La declaración debe ser una cadena literal simple, no cualquier otro tipo de expresión. La cadena de documentación del objeto de código está disponible en el __doc__atributo de ese objeto de código y a través de la helpfunción.
El siguiente archivo de Python muestra la declaración de cadenas de documentación dentro de un archivo fuente de Python:
"""La cadena de documentación del módulo"""clase MyClass : """La cadena de documentación de la clase""" def my_method ( self ): """La cadena de documentación del método""" def my_function (): """La cadena de documentación de la función""" Suponiendo que el código anterior se guardó como mymodule.py , la siguiente es una sesión interactiva que muestra cómo se puede acceder a las cadenas de documentación:
>>> import mymodule >>> help ( mymodule ) La cadena de documentación del módulo >>> help ( mymodule . MyClass ) La cadena de documentación de la clase >>> help ( mymodule . MyClass . my_method ) La cadena de documentación del método >>> help ( mymodule . my_function ) La cadena de documentación de la función >>>