उनके दस्तावेज में स्फिंक्स के लिए एक सिद्धांत है । विशेष रूप से वे निम्नलिखित दिखाते हैं:
def public_fn_with_googley_docstring(name, state=None):
"""This function does something.
Args:
name (str): The name to use.
Kwargs:
state (bool): Current state to be in.
Returns:
int. The return code::
0 -- Success!
1 -- No good.
2 -- Try again.
Raises:
AttributeError, KeyError
A really great idea. A way you might use me is
>>> print public_fn_with_googley_docstring(name='foo', state=None)
0
BTW, this always returns 0. **NEVER** use with :class:`MyPublicClass`.
"""
return 0
हालांकि आपने पूछा गूढ़ व्यक्तिस्पष्ट रूप से, मैं Google पायथन स्टाइल गाइड की ओर भी इशारा करूंगा । उनके डॉकस्ट्रिंग उदाहरण का अर्थ यह लगता है कि वे विशेष रूप से क्वार्ग्स को नहीं कहते हैं। (other_silly_variable = कोई नहीं)
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
"""Fetches rows from a Bigtable.
Retrieves rows pertaining to the given keys from the Table instance
represented by big_table. Silly things may happen if
other_silly_variable is not None.
Args:
big_table: An open Bigtable Table instance.
keys: A sequence of strings representing the key of each table row
to fetch.
other_silly_variable: Another optional variable, that has a much
longer name than the other args, and which does nothing.
Returns:
A dict mapping keys to the corresponding table row data
fetched. Each row is represented as a tuple of strings. For
example:
{'Serak': ('Rigel VII', 'Preparer'),
'Zim': ('Irk', 'Invader'),
'Lrrr': ('Omicron Persei 8', 'Emperor')}
If a key from the keys argument is missing from the dictionary,
then that row was not found in the table.
Raises:
IOError: An error occurred accessing the bigtable.Table object.
"""
pass
एबीबी के पास उपप्रबंध प्रबंधन प्रलेखन को संदर्भित करने के स्वीकृत उत्तर के बारे में एक प्रश्न है। यदि आप एक मॉड्यूल आयात करते हैं, तो आप इंस्पेक्ट.गेटसोर्स के माध्यम से मॉड्यूल डॉकस्ट्रिंग्स को जल्दी से देख सकते हैं।
साइलेंट घोस्ट की सिफारिश का उपयोग करते हुए अजगर दुभाषिया से एक उदाहरण:
>>> import subprocess
>>> import inspect
>>> import print inspect.getsource(subprocess)
बेशक आप मदद फ़ंक्शन के माध्यम से मॉड्यूल प्रलेखन भी देख सकते हैं। उदाहरण के लिए मदद (उपप्रकार)
मैं व्यक्तिगत रूप से एक उदाहरण के रूप में kwargs के लिए उपप्रकार डॉकस्ट्रिंग का प्रशंसक नहीं हूं, लेकिन Google उदाहरण की तरह यह kwargs को स्पष्ट रूप से सूचीबद्ध नहीं करता है जैसा कि स्फिंक्स प्रलेखन उदाहरण में दिखाया गया है।
def call(*popenargs, **kwargs):
"""Run command with arguments. Wait for command to complete, then
return the returncode attribute.
The arguments are the same as for the Popen constructor. Example:
retcode = call(["ls", "-l"])
"""
return Popen(*popenargs, **kwargs).wait()
मैं एबीबी के प्रश्न के इस उत्तर को शामिल कर रहा हूं क्योंकि यह ध्यान देने योग्य है कि आप किसी भी मॉड्यूल के स्रोत या प्रलेखन की समीक्षा कर सकते हैं इस तरह से अंतर्दृष्टि और प्रेरणा के लिए अपने कोड की टिप्पणी कर सकते हैं।