En programación , una cadena de documentos es una cadena literal especificada en el código fuente que se usa, como un comentario , para documentar un segmento específico de código. A diferencia de los comentarios de código fuente convencionales, o incluso comentarios formateados específicamente como la documentación de Javadoc , las cadenas de documentos no se eliminan del árbol de fuentes cuando se analizan 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 .
Parece haber sido introducido por primera vez en la implementación TECO original de Emacs . [1]
Los lenguajes que admiten cadenas de documentación incluyen Python , Lisp , Elixir , Clojure , [2] Gherkin , [3] Julia [4] y Haskell . [5]
Ejemplos de implementación
Elixir
La documentación se admite a nivel de idioma, en forma de cadenas de documentación. Markdown es el lenguaje de marcado de facto elegido por Elixir para usar en cadenas de documentos:
def module MyModule do @moduledoc "" " Documentación para mi módulo. Con ** formato **. " "" @doc "Hola" def world do "World" end end
Ceceo
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 documentos cuando lo desee, por cualquier motivo. Cuando se guardan, las cadenas de documentos se pueden ver y cambiar mediante la función DOCUMENTACIÓN. [6] Por ejemplo:
( defun foo () "hola" nulo ) ( documentación # función ' foo ' ) => "hola"
Pitón
La práctica común de documentar un objeto de código al comienzo de su definición se captura mediante la adición de sintaxis de cadena de documentos en el lenguaje Python.
La cadena de documentación de un objeto de código Python (un módulo, clase o 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 un literal de cadena simple, no ningún otro tipo de expresión. La cadena de documentación para el objeto de código está disponible en el __doc__
atributo de ese objeto de código y a través de la help
función.
El siguiente archivo de Python muestra la declaración de cadenas de documentos dentro de un archivo fuente de Python:
"" "La cadena de documentos del módulo" ""class MyClass : "" "La cadena de documentos de la clase" "" def my_method ( self ): "" "La cadena de documentos del método" ""def my_function (): "" "La cadena de documentos 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 documentos:
>>> import mymodule >>> help ( mymodule ) La cadena de documentos del módulo >>> ayuda ( mymodule . MyClass ) La cadena de documentos de la clase >>> ayuda ( mymodule . MyClass . my_method ) La cadena de documentos del método >>> ayuda ( mymodule . my_function ) La cadena de documentación de la función >>>
Herramientas que utilizan cadenas de documentos
- cobra -doc (Cobra)
- doctest (Python)
- Epydoc (Python)
- Pydoc (Python)
- Esfinge (pitón)
Ver también
- Programación alfabetizada : paradigma alternativo de comentarios de código
- Documentación antigua simple: documentación de Perl
Referencias
- ^ "EMACS: el editor de pantalla personalizable y extensible" .
- ^ Definición de función con docstring en Clojure
- ^ "Argumentos de paso: cadenas de documentos" . Archivado desde el original el 31 de enero de 2016 . Consultado el 22 de junio de 2016 .
- ^ http://docs.julialang.org/en/stable/manual/documentation/
- ^ https://hackage.haskell.org/package/docstrings
- ^ CLHS: DOCUMENTACIÓN de función genérica estándar ...
enlaces externos
- Python Docstrings en la página de Sourceforge de Epydoc
- Documentación en GNU Emacs Lisp
- Sección de la documentación de doxygen sobre cadenas de documentación de Python