|
17
by Jonathan Lange
LICENSE it as MIT. |
1 |
# Copyright (c) 2007-2010 testdoc authors. See LICENSE for details.
|
2 |
||
|
9
by jml@canonical.com
Move extract_docs into reflect and expand it to support internal comments. |
3 |
import unittest |
4 |
||
5 |
from testdoc.reflect import extract_docs |
|
6 |
||
7 |
||
8 |
class TestExtractDocs(unittest.TestCase): |
|
9 |
"""Extract whatever documentation we can from Python objects.
|
|
10 |
||
11 |
Python modules, classes, methods and functions can be documented in several
|
|
12 |
ways. They can have docstrings, they can be preceded by comments, or they
|
|
13 |
can have comments that form the first lines of their implementation.
|
|
14 |
||
15 |
We want to extract whatever documentation we can from these Python blocks
|
|
16 |
so we can include it in our documentation.
|
|
17 |
"""
|
|
18 |
||
19 |
def test_no_documentation(self): |
|
20 |
"""If the object has no documentation at all, then extract_docs should
|
|
21 |
return None."""
|
|
22 |
def undocumented(): |
|
23 |
pass
|
|
24 |
self.assertEqual(None, extract_docs(undocumented)) |
|
25 |
||
26 |
def test_extracts_docstring(self): |
|
27 |
"""If the object has a docstring, then that is the documentation we
|
|
28 |
want to use."""
|
|
29 |
||
30 |
def docstringed(): |
|
31 |
"""docstring"""
|
|
32 |
self.assertEqual('docstring', extract_docs(docstringed)) |
|
33 |
||
34 |
||
35 |
def test_extracts_preceding_comment(self): |
|
36 |
"""If the object has a comment preceding it, then extract that comment.
|
|
37 |
"""
|
|
38 |
||
39 |
# pre-commented
|
|
40 |
# multi-lines
|
|
41 |
def precommented(): |
|
42 |
pass
|
|
43 |
self.assertEqual('pre-commented\nmulti-lines', |
|
44 |
extract_docs(precommented)) |
|
45 |
||
46 |
def test_extracts_internal_comment(self): |
|
47 |
"""If the object has a comment as part of it's internals, then extract
|
|
48 |
that comment. The first non-comment line (even a blank one) terminates
|
|
49 |
the comment."""
|
|
50 |
||
51 |
def commented(): |
|
52 |
# line 1
|
|
53 |
# line 2
|
|
54 |
#
|
|
55 |
# line 4
|
|
56 |
||
57 |
# not part of the main comment
|
|
58 |
pass
|
|
59 |
self.assertEqual('line 1\nline 2\n\nline 4', extract_docs(commented)) |
|
60 |
||
61 |
def test_docstring_preferred(self): |
|
62 |
"""If an object has a docstring _and_ comments, then the docstring is
|
|
63 |
the preferred documentation.
|
|
64 |
"""
|
|
65 |
||
66 |
# comment
|
|
67 |
def docstring_and_comment(): |
|
68 |
"""docstring"""
|
|
69 |
||
70 |
self.assertEqual('docstring', extract_docs(docstring_and_comment)) |
|
71 |
||
72 |
def test_external_comment_preferred(self): |
|
73 |
"""Very few people use external comments for documenting classes or
|
|
74 |
methods. Still, if someone _is_ using external comments, they probably
|
|
75 |
expect them to be used for documentation. Thus, the external comment is
|
|
76 |
preferred over the internal comment.
|
|
77 |
"""
|
|
78 |
||
79 |
# external
|
|
80 |
def commented(): |
|
81 |
# internal
|
|
82 |
pass
|
|
83 |
||
84 |
self.assertEqual('external', extract_docs(commented)) |