Docstringing (was RE: [Pythonmac-SIG] Re. [ann] AppScripting 0.1. 0)

[Schollnick, Benjamin]

> On the to-do list.:) For my education, is it normal practice to put 
> docstrings on everything - both private and public - or just on the 
> public stuff? I've rather assumed that docstrings are supplied for 
> the benefit of end users, rather than developers who can read 
> comments as easily.

Honestly, in my opinion, I Docstring everything...  But that is more
for my benefit, than anyone elses.  This way when I come back later,
even the private areas are documented.  I just make sure to
mark the "Low Level areas", as such.  With note saying that they should
only be called by other routines....

I didn't think about this, but since we're on the topic.

Do other people use a Common Docstring template?

I have not seen any good Docstring references, but I must admit,
I have not reread the Python's Documentation on Documentation in a long
while....

I generally attempt to include the following in my DocStrings...

	1) General description
	2) Input list
	3) Output List
	4) Example, with as much detail as reasonable.
	(optional) Additional notes


For example:

1)
    """ Wrapper around the reg_interface module.  Adds support for multiple
        HKEY sources, and reads the different data types from the remote
        registry.

        Inputs -
            reg_interface   - Registry Interface Object
            hkey            - The HKEY to be searched (i.e.
Hkey_local_machine)
                                HKCU - Hkey_Current_User
                                HKLM - Hkey Local Machine
                                
            keystring       - The full key path to the keyname element
            keyname         - The name of the element to be retrieved.
            data_type       - The data type of the registry element/keyname.
                                Defaults to "S" (String)
                                D == Dword

        Outputs -
            x, reg_value

            x               - Unknown
            reg_value       - The values of the Registry Entry

        Example:
            a = win32com.client.Dispatch ("WbemScripting.SWbemLocator")
            b = a.ConnectServer ( hostname, "root/default", username,
password)
            b.Security_.ImpersonationLevel = 3
            c = wmi._wmi_object (b.Get ("StdRegProv"))
            x, reg_value = peek_registry (c, hkey, reg_path, reg_subkey,
reg_type)
    """


2)
	def     return_ds_user_password (self):
                """Return the current setting for User Password.

                Input:
                    None
                    
                Output:
                    String containing the current User Password.
                    Empty String ("") returned for empty password.
                    ("" is the default startup value)

                Example:
                    % print ts_ds_server.return_ds_user_password ()
                        
                    % ts_ds_server.set_ds_user_name ("tmasaki")
                    % ts_ds_server.set_ds_user_password ("ryoko")
                    % print ts_ds_server.return_ds_user_name()
                        tmasaki
                    % print ts_ds_server.return_ds_user_password ()
                        ryoko
                """