473,545 Members | 757 Online
Bytes | Software Development & Data Engineering Community
+ Post

Home Posts Topics Members FAQ

Python Documentation Standards

Doc strings provide us with a great opportunity to illuminate our code.

In the example below, __init__ refers us to the class's documentation,
but the class doc doesn't help much.

Are there any guideline which cover such things?

PEP 8 <http://www.python.org/doc/peps/pep-0008/> has general advice.
PEP 257 <http://www.python.org/doc/peps/pep-0257/> provides more
detailed advice.

list provides a trivial example because it is very well documented
elsewhere but it does provide a template for others.

Colin W.

Colin W.
list.__init__._ _doc__ 'x.__init__(... ) initializes x; see x.__class__.__d oc__ for signature' list.__new__.__ doc__ 'T.__new__(S, ...) -> a new object with type S, a subtype of T' list.__class__. __doc__ "type(objec t) -> the object's type\ntype(name , bases, dict) -> a new type"

Mar 16 '06 #1
3 1583
Colin J. Williams wrote:
Doc strings provide us with a great opportunity to illuminate our code.

In the example below, __init__ refers us to the class's documentation,
but the class doc doesn't help much.


It doesn't?
print list.__doc__

list() -> new list
list(sequence) -> new list initialized from sequence's items

What is it you were hoping to see in constructor documentation?

STeVe
Mar 16 '06 #2
Steven Bethard wrote:
Colin J. Williams wrote:
Doc strings provide us with a great opportunity to illuminate our code.

In the example below, __init__ refers us to the class's documentation,
but the class doc doesn't help much.


It doesn't?
print list.__doc__ list() -> new list
list(sequence) -> new list initialized from sequence's items

What is it you were hoping to see in constructor documentation?

STeVe


How about this?:
print list.__doc__

list() -> new list
list(sequence) -> new list initialized from sequence's items
See http://docs.python.org/lib/built-in-funcs.html#l2h-44

although it would be better if the online docs had a more permanent looking
anchor.
Mar 16 '06 #3
Steven Bethard wrote:
Colin J. Williams wrote:
Doc strings provide us with a great opportunity to illuminate our code.

In the example below, __init__ refers us to the class's documentation,
but the class doc doesn't help much.

It doesn't?
>>> print list.__doc__

list() -> new list
list(sequence) -> new list initialized from sequence's items

What is it you were hoping to see in constructor documentation?

STeVe

You are right, I didn't dig far enough.

Colin W.
Mar 17 '06 #4

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

12
4024
by: Xah Lee | last post by:
Python Doc Problem Example Quote from: http://docs.python.org/lib/module-os.path.html ---------- split( path) Split the pathname path into a pair, (head, tail) where tail is the last pathname component and head is everything leading up to that. The tail part will never contain a slash; if path ends in a slash, tail will be empty. If...
0
929
by: Christoph Zwerschke | last post by:
I just thought it would be nice to have a standardized place to put the accompanying documentation for Python site packages, and something like a hook to register documentation so that all installed site packages can install links to their documentation in the Python Documentation Index. Are there already any thoughts or standards on how to...
0
7456
marktang
by: marktang | last post by:
ONU (Optical Network Unit) is one of the key components for providing high-speed Internet services. Its primary function is to act as an endpoint device located at the user's premises. However, people are often confused as to whether an ONU can Work As a Router. In this blog post, we’ll explore What is ONU, What Is Router, ONU & Router’s main...
0
7390
by: Hystou | last post by:
Most computers default to English, but sometimes we require a different language, especially when relocating. Forgot to request a specific language before your computer shipped? No problem! You can effortlessly switch the default language on Windows 10 without reinstalling. I'll walk you through it. First, let's disable language...
0
7802
jinu1996
by: jinu1996 | last post by:
In today's digital age, having a compelling online presence is paramount for businesses aiming to thrive in a competitive landscape. At the heart of this digital strategy lies an intricately woven tapestry of website design and digital marketing. It's not merely about having a website; it's about crafting an immersive digital experience that...
1
7410
by: Hystou | last post by:
Overview: Windows 11 and 10 have less user interface control over operating system update behaviour than previous versions of Windows. In Windows 11 and 10, there is no way to turn off the Windows Update option using the Control Panel or Settings app; it automatically checks for updates and installs any it finds, whether you like it or not. For...
0
7744
tracyyun
by: tracyyun | last post by:
Dear forum friends, With the development of smart home technology, a variety of wireless communication protocols have appeared on the market, such as Zigbee, Z-Wave, Wi-Fi, Bluetooth, etc. Each protocol has its own unique characteristics and advantages, but as a user who is planning to build a smart home system, I am a bit confused by the...
0
5960
agi2029
by: agi2029 | last post by:
Let's talk about the concept of autonomous AI software engineers and no-code agents. These AIs are designed to manage the entire lifecycle of a software development project—planning, coding, testing, and deployment—without human intervention. Imagine an AI that can take a project description, break it down, write the code, debug it, and then...
1
5320
isladogs
by: isladogs | last post by:
The next Access Europe User Group meeting will be on Wednesday 1 May 2024 starting at 18:00 UK time (6PM UTC+1) and finishing by 19:30 (7.30PM). In this session, we are pleased to welcome a new presenter, Adolph Dupré who will be discussing some powerful techniques for using class modules. He will explain when you may want to use classes...
0
3442
by: TSSRALBI | last post by:
Hello I'm a network technician in training and I need your help. I am currently learning how to create and manage the different types of VPNs and I have a question about LAN-to-LAN VPNs. The last exercise I practiced was to create a LAN-to-LAN VPN between two Pfsense firewalls, by using IPSEC protocols. I succeeded, with both firewalls in...
1
1869
by: 6302768590 | last post by:
Hai team i want code for transfer the data from one system to another through IP address by using C# our system has to for every 5mins then we have to update the data what the data is updated we have to send another system

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.