Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 4491466

Browse files
committed
swap "Popular Docstring Formats" and "Documenting other stuff" sections
1 parent 0f509af commit 4491466

File tree

1 file changed

+77
-77
lines changed

1 file changed

+77
-77
lines changed

‎basics/docstrings.md‎

Lines changed: 77 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -121,6 +121,83 @@ It's recommended to always use `"""strings like this"""` for docstrings,
121121
even if the docstring is only one line long. This way it's easy to add
122122
more stuff to it later.
123123

124+
## Documenting other stuff
125+
126+
Docstrings aren't actually limited to functions. You can use them for
127+
documenting [classes](classes.md) and their methods too. For example,
128+
let's make a file like this and save it to `test.py`:
129+
130+
```python
131+
"""A test module.
132+
133+
It contains a class and a function.
134+
"""
135+
136+
137+
class Thing:
138+
"""This is a test class."""
139+
140+
def thingy(self):
141+
"""This is a test method."""
142+
print("hello")
143+
144+
145+
def do_hello():
146+
"""This is a test function."""
147+
thing = Thing()
148+
thing.thingy()
149+
```
150+
151+
Then we can import it and call help on it:
152+
153+
[comment]: # (github screws up syntax highlighting here)
154+
155+
```
156+
>>> import test
157+
>>> help(test)
158+
Help on module testie:
159+
160+
NAME
161+
testie - A test module.
162+
163+
DESCRIPTION
164+
It contains a class and a function.
165+
166+
CLASSES
167+
builtins.object
168+
Thing
169+
170+
class Thing(builtins.object)
171+
| This is a test class.
172+
|
173+
| Methods defined here:
174+
|
175+
| thingy(self)
176+
| This is a test method.
177+
|
178+
| ----------------------------------------------------------------------
179+
| Data descriptors defined here:
180+
|
181+
| __dict__
182+
| dictionary for instance variables (if defined)
183+
|
184+
| __weakref__
185+
| list of weak references to the object (if defined)
186+
187+
FUNCTIONS
188+
do_hello()
189+
This is a test function.
190+
191+
FILE
192+
/home/akuli/testie.py
193+
```
194+
195+
That's pretty cool. We just added docstrings to our code and Python made
196+
this thing out of it.
197+
198+
You might be wondering what `__weakref__` is. You don't need to care
199+
about it, and I think it would be better if `help()` would hide it.
200+
124201
## Popular Docstring Formats
125202

126203
There are different styles for writing docstrings. If you are contributing to
@@ -254,83 +331,6 @@ class Vehicles:
254331
pass
255332
```
256333

257-
## Documenting other stuff
258-
259-
Docstrings aren't actually limited to functions. You can use them for
260-
documenting [classes](classes.md) and their methods too. For example,
261-
let's make a file like this and save it to `test.py`:
262-
263-
```python
264-
"""A test module.
265-
266-
It contains a class and a function.
267-
"""
268-
269-
270-
class Thing:
271-
"""This is a test class."""
272-
273-
def thingy(self):
274-
"""This is a test method."""
275-
print("hello")
276-
277-
278-
def do_hello():
279-
"""This is a test function."""
280-
thing = Thing()
281-
thing.thingy()
282-
```
283-
284-
Then we can import it and call help on it:
285-
286-
[comment]: # (github screws up syntax highlighting here)
287-
288-
```
289-
>>> import test
290-
>>> help(test)
291-
Help on module testie:
292-
293-
NAME
294-
testie - A test module.
295-
296-
DESCRIPTION
297-
It contains a class and a function.
298-
299-
CLASSES
300-
builtins.object
301-
Thing
302-
303-
class Thing(builtins.object)
304-
| This is a test class.
305-
|
306-
| Methods defined here:
307-
|
308-
| thingy(self)
309-
| This is a test method.
310-
|
311-
| ----------------------------------------------------------------------
312-
| Data descriptors defined here:
313-
|
314-
| __dict__
315-
| dictionary for instance variables (if defined)
316-
|
317-
| __weakref__
318-
| list of weak references to the object (if defined)
319-
320-
FUNCTIONS
321-
do_hello()
322-
This is a test function.
323-
324-
FILE
325-
/home/akuli/testie.py
326-
```
327-
328-
That's pretty cool. We just added docstrings to our code and Python made
329-
this thing out of it.
330-
331-
You might be wondering what `__weakref__` is. You don't need to care
332-
about it, and I think it would be better if `help()` would hide it.
333-
334334
## When should we use docstrings?
335335

336336
Always use docstrings when writing code that other people will import.

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /