📄 ch07s07.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd"><html><head><meta http-equiv="Content-Type" content="text/html; charset=gb2312"><style type="text/css"><!--@import url(stylesheet/text.css);@import url(stylesheet/box.css);--></style><title>简明 Python 教程 / 函数 / DocStrings </title></head><body><table width="100%"><tr><th colspan="3" align="center"><span class="header">简明 Python 教程</span></th></tr><th colspan="3" align="center">第7章 函数</th><tr><th width="20%" align="left"><a href="ch07s06.html">上一页</a></th><th width="60%" align="center"><span class="header2">DocStrings</span></th><th align="right"><a href="ch07s08.html">下一页</a></th></tr></table><hr noshade><h1>DocStrings</h1><p>Python有一个很奇妙的特性，称为 <dfn>文档字符串</dfn> ，它通常被简称为 <dfn>docstrings</dfn> 。DocStrings是一个重要的工具，由于它帮助你的程序文档更加简单易懂，你应该尽量使用它。你甚至可以在程序运行的时候，从函数恢复文档字符串！</p><h2><a name="using">使用DocStrings</a></h2><p class="exampletitle"><a name="e78">例7.8 使用DocStrings</a></p><p class="filebox"><code class="comment">#!/usr/bin/python<br># Filename: func_doc.py</code><br><br><code class="key">def </code><code class="func">printMax</code><code>(x, y):</code><br><code class="cite"> '''Prints the maximum of two numbers.<br><br> The two values must be integers.'''</code><br><code> x = </code><code class="func">int</code><code>(x) </code><code class="comment"># convert to integers, if possible</code><br><code> y = </code><code class="func">int</code><code>(y)</code><br><br><code class="key"> if </code><code>x > y:</code><br><code class="key"> print </code><code>x, </code><code class="cite">'is maximum'</code><br><code class="key"> else</code><code>:</code><br><code class="key"> print </code><code>y, </code><code class="cite">'is maximum'</code><br><br><code>printMax(</code><code class="cite">3</code><code>, </code><code class="cite">5</code><code>)</code><br><code class="key">print </code><code>printMax.__doc__</code></p><p>（源文件：<a href="code/func_doc.py">code/func_doc.py</a>）</p><h2>输出</h2><p class="codebox">$ python func_doc.py<br>5 is maximum<br>Prints the maximum of two numbers.<br><br> The two values must be integers.</p><h2>它如何工作</h2><p>在函数的第一个逻辑行的字符串是这个函数的 <dfn>文档字符串</dfn> 。注意，DocStrings也适用于<a href="ch08.html">模块</a>和<a href="ch11.html">类</a>，我们会在后面相应的章节学习它们。</p><p>文档字符串的惯例是一个多行字符串，它的首行以大写字母开始，句号结尾。第二行是空行，从第三行开始是详细的描述。 <dfn>强烈建议</dfn> 你在你的函数中使用文档字符串时遵循这个惯例。</p><p>你可以使用<code>__doc__</code>（注意双下划线）调用<code>printMax</code>函数的文档字符串属性（属于函数的名称）。请记住Python把 <dfn>每一样东西</dfn> 都作为对象，包括这个函数。我们会在后面的<a href="ch11.html">类</a>一章学习更多关于对象的知识。</p><p>如果你已经在Python中使用过<code>help()</code>，那么你已经看到过DocStings的使用了！它所做的只是抓取函数的<code>__doc__</code>属性，然后整洁地展示给你。你可以对上面这个函数尝试一下——只是在你的程序中包括<code>help(printMax)</code>。记住按<strong>q</strong>退出<code>help</code>。</p><p>自动化工具也可以以同样的方式从你的程序中提取文档。因此，我 <dfn>强烈建议</dfn> 你对你所写的任何正式函数编写文档字符串。随你的Python发行版附带的<strong>pydoc</strong>命令，与<code>help()</code>类似地使用DocStrings。</p><hr noshade><table width="100%"><tr><th width="20%" align="left"><a href="ch07s06.html">上一页</a></th><th width="60%" align="center"><a href="ch07.html">上一级</a></th><th width="20%" align="right"><a href="ch07s08.html">下一页</a></th></tr><tr><th width="20%" align="left">return语句</th><th width="60%" align="center"><a href="index.html">首页</a></th><th align="right">概括</th></tr></table></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -