CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 216 – Docstring Format | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0216/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 216 – Docstring Format | peps.python.org'> <meta property="og:description" content="Named Python objects, such as modules, classes and functions, have a string attribute called __doc__. If the first expression inside the definition is a literal string, that string is assigned to the __doc__ attribute."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0216/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="Named Python objects, such as modules, classes and functions, have a string attribute called __doc__. If the first expression inside the definition is a literal string, that string is assigned to the __doc__ attribute."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 216</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> <span class="visually-hidden">Toggle light / dark / auto colour theme</span> </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 216 – Docstring Format</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">Moshe Zadka <moshez at zadka.site.co.il></dd> <dt class="field-even">Status<span class="colon">:</span></dt> <dd class="field-even"><abbr title="Removed from consideration by sponsor or authors">Withdrawn</abbr></dd> <dt class="field-odd">Type<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Non-normative PEP containing background, guidelines or other information relevant to the Python ecosystem">Informational</abbr></dd> <dt class="field-even">Created<span class="colon">:</span></dt> <dd class="field-even">31-Jul-2000</dd> <dt class="field-odd">Post-History<span class="colon">:</span></dt> <dd class="field-odd"><p></p></dd> <dt class="field-even">Superseded-By<span class="colon">:</span></dt> <dd class="field-even"><a class="reference external" href="../pep-0287/">287</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#perl-documentation">Perl Documentation</a></li> <li><a class="reference internal" href="#java-documentation">Java Documentation</a></li> <li><a class="reference internal" href="#python-docstring-goals">Python Docstring Goals</a></li> <li><a class="reference internal" href="#high-level-solutions">High Level Solutions</a></li> <li><a class="reference internal" href="#docstring-format-goals">Docstring Format Goals</a></li> <li><a class="reference internal" href="#docstring-contents">Docstring Contents</a></li> <li><a class="reference internal" href="#docstring-basic-structure">Docstring Basic Structure</a></li> <li><a class="reference internal" href="#unresolved-issues">Unresolved Issues</a></li> <li><a class="reference internal" href="#rejected-suggestions">Rejected Suggestions</a></li> </ul> </details></section> <div class="pep-banner sticky-banner deprecated withdrawn admonition important"> <p class="admonition-title">Important</p> <p>This PEP has been withdrawn.</p> <p class="close-button">×</p> <p>It has been superseded by <a class="pep reference internal" href="../pep-0287/" title="PEP 287 – reStructuredText Docstring Format">PEP 287</a>.</p> <p></p> </div> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> <p>Named Python objects, such as modules, classes and functions, have a string attribute called <code class="docutils literal notranslate"><span class="pre">__doc__</span></code>. If the first expression inside the definition is a literal string, that string is assigned to the <code class="docutils literal notranslate"><span class="pre">__doc__</span></code> attribute.</p> <p>The <code class="docutils literal notranslate"><span class="pre">__doc__</span></code> attribute is called a documentation string, or docstring. It is often used to summarize the interface of the module, class or function. However, since there is no common format for documentation string, tools for extracting docstrings and transforming those into documentation in a standard format (e.g., DocBook) have not sprang up in abundance, and those that do exist are for the most part unmaintained and unused.</p> </section> <section id="perl-documentation"> <h2><a class="toc-backref" href="#perl-documentation" role="doc-backlink">Perl Documentation</a></h2> <p>In Perl, most modules are documented in a format called POD – Plain Old Documentation. This is an easy-to-type, very low level format which integrates well with the Perl parser. Many tools exist to turn POD documentation into other formats: info, HTML and man pages, among others. However, in Perl, the information is not available at run-time.</p> </section> <section id="java-documentation"> <h2><a class="toc-backref" href="#java-documentation" role="doc-backlink">Java Documentation</a></h2> <p>In Java, special comments before classes and functions function to document the code. A program to extract these, and turn them into HTML documentation is called javadoc, and is part of the standard Java distribution. However, the only output format that is supported is HTML, and JavaDoc has a very intimate relationship with HTML.</p> </section> <section id="python-docstring-goals"> <h2><a class="toc-backref" href="#python-docstring-goals" role="doc-backlink">Python Docstring Goals</a></h2> <p>Python documentation string are easy to spot during parsing, and are also available to the runtime interpreter. This double purpose is a bit problematic, sometimes: for example, some are reluctant to have too long docstrings, because they do not want to take much space in the runtime. In addition, because of the current lack of tools, people read objects’ docstrings by “print”ing them, so a tendency to make them brief and free of markups has sprung up. This tendency hinders writing better documentation-extraction tools, since it causes docstrings to contain little information, which is hard to parse.</p> </section> <section id="high-level-solutions"> <h2><a class="toc-backref" href="#high-level-solutions" role="doc-backlink">High Level Solutions</a></h2> <p>To counter the objection that the strings take up place in the running program, it is suggested that documentation extraction tools will concatenate a maximum prefix of string literals which appear in the beginning of a definition. The first of these will also be available in the interactive interpreter, so it should contain a few summary lines.</p> </section> <section id="docstring-format-goals"> <h2><a class="toc-backref" href="#docstring-format-goals" role="doc-backlink">Docstring Format Goals</a></h2> <p>These are the goals for the docstring format, as discussed ad nauseam in the doc-sig.</p> <ol class="arabic simple"> <li>It must be easy to type with any standard text editor.</li> <li>It must be readable to the casual observer.</li> <li>It must not contain information which can be deduced from parsing the module.</li> <li>It must contain sufficient information so it can be converted to any reasonable markup format.</li> <li>It must be possible to write a module’s entire documentation in docstrings, without feeling hampered by the markup language.</li> </ol> </section> <section id="docstring-contents"> <h2><a class="toc-backref" href="#docstring-contents" role="doc-backlink">Docstring Contents</a></h2> <p>For requirement 5. above, it is needed to specify what must be in docstrings.</p> <p>At least the following must be available:</p> <ol class="loweralpha"> <li>A tag that means “this is a Python <em>something</em>, guess what”<p>Example: In the sentence “The POP3 class”, we need to markup “POP3” so. The parser will be able to guess it is a class from the contents of the <code class="docutils literal notranslate"><span class="pre">poplib</span></code> module, but we need to make it guess.</p> </li> <li>Tags that mean “this is a Python class/module/class var/instance var…”<p>Example: The usual Python idiom for singleton class <code class="docutils literal notranslate"><span class="pre">A</span></code> is to have <code class="docutils literal notranslate"><span class="pre">_A</span></code> as the class, and <code class="docutils literal notranslate"><span class="pre">A</span></code> a function which returns <code class="docutils literal notranslate"><span class="pre">_A</span></code> objects. It’s usual to document the class, nonetheless, as being <code class="docutils literal notranslate"><span class="pre">A</span></code>. This requires the strength to say “The class <code class="docutils literal notranslate"><span class="pre">A</span></code>” and have <code class="docutils literal notranslate"><span class="pre">A</span></code> hyperlinked and marked-up as a class.</p> </li> <li>An easy way to include Python source code/Python interactive sessions</li> <li>Emphasis/bold</li> <li>List/tables</li> </ol> </section> <section id="docstring-basic-structure"> <h2><a class="toc-backref" href="#docstring-basic-structure" role="doc-backlink">Docstring Basic Structure</a></h2> <p>The documentation strings will be in StructuredTextNG (<a class="reference external" href="http://www.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG">http://www.zope.org/Members/jim/StructuredTextWiki/StructuredTextNG</a>) Since StructuredText is not yet strong enough to handle (a) and (b) above, we will need to extend it. I suggest using <code class="docutils literal notranslate"><span class="pre">[<optional</span> <span class="pre">description>:python</span> <span class="pre">identifier]</span></code>. E.g.: <code class="docutils literal notranslate"><span class="pre">[class:POP3]</span></code>, <code class="docutils literal notranslate"><span class="pre">[:POP3.list]</span></code>, etc. If the description is missing, a guess will be made from the text.</p> </section> <section id="unresolved-issues"> <h2><a class="toc-backref" href="#unresolved-issues" role="doc-backlink">Unresolved Issues</a></h2> <p>Is there a way to escape characters in ST? If so, how? (example: * at the beginning of a line without being bullet symbol)</p> <p>Is my suggestion above for Python symbols compatible with ST-NG? How hard would it be to extend ST-NG to support it?</p> <p>How do we describe input and output types of functions?</p> <p>What additional constraint do we enforce on each docstring? (module/class/function)?</p> <p>What are the guesser rules?</p> </section> <section id="rejected-suggestions"> <h2><a class="toc-backref" href="#rejected-suggestions" role="doc-backlink">Rejected Suggestions</a></h2> <p>XML – it’s very hard to type, and too cluttered to read it comfortably.</p> </section> </section> <hr class="docutils" /> <p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0216.rst">https://github.com/python/peps/blob/main/peps/pep-0216.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0216.rst">2024-04-14 20:08:31 GMT</a></p> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#perl-documentation">Perl Documentation</a></li> <li><a class="reference internal" href="#java-documentation">Java Documentation</a></li> <li><a class="reference internal" href="#python-docstring-goals">Python Docstring Goals</a></li> <li><a class="reference internal" href="#high-level-solutions">High Level Solutions</a></li> <li><a class="reference internal" href="#docstring-format-goals">Docstring Format Goals</a></li> <li><a class="reference internal" href="#docstring-contents">Docstring Contents</a></li> <li><a class="reference internal" href="#docstring-basic-structure">Docstring Basic Structure</a></li> <li><a class="reference internal" href="#unresolved-issues">Unresolved Issues</a></li> <li><a class="reference internal" href="#rejected-suggestions">Rejected Suggestions</a></li> </ul> <br> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0216.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>