[Python-checkins] python/dist/src/PC _winreg.c,1.9,1.10 winsound.c,1.9,1.10

Thu, 13 Jun 2002 13:33:04 -0700

Update of /cvsroot/python/python/dist/src/PC
In directory usw-pr-cvs1:/tmp/cvs-serv14210/PC

Modified Files:
	_winreg.c winsound.c 
Log Message:
Patch #568124: Add doc string macros.

Index: _winreg.c
===================================================================
RCS file: /cvsroot/python/python/dist/src/PC/_winreg.c,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** _winreg.c	31 Mar 2002 14:37:44 -0000	1.9
--- _winreg.c	13 Jun 2002 20:33:01 -0000	1.10
***************
*** 35,39 ****

  /* Doc strings */
! static char module_doc[] =
  "This module provides access to the Windows registry API.\n"
  "\n"
--- 35,39 ----

  /* Doc strings */
! PyDoc_STRVAR(module_doc,
  "This module provides access to the Windows registry API.\n"
  "\n"
***************
*** 69,76 ****
  "Integer constants:\n"
  "Many constants are defined - see the documentation for each function\n"
! "to see what constants are used, and where.";

! static char CloseKey_doc[] =
  "CloseKey(hkey) - Closes a previously opened registry key.\n"
  "\n"
--- 69,76 ----
  "Integer constants:\n"
  "Many constants are defined - see the documentation for each function\n"
! "to see what constants are used, and where.");

! PyDoc_STRVAR(CloseKey_doc,
  "CloseKey(hkey) - Closes a previously opened registry key.\n"
  "\n"
***************
*** 78,84 ****
  "\n"
  "Note that if the key is not closed using this method, it will be\n"
! "closed when the hkey object is destroyed by Python.";

! static char ConnectRegistry_doc[] =
  "key = ConnectRegistry(computer_name, key) - "
  "Establishes a connection to a predefined registry handle on another computer.\n"
--- 78,84 ----
  "\n"
  "Note that if the key is not closed using this method, it will be\n"
! "closed when the hkey object is destroyed by Python.");

! PyDoc_STRVAR(ConnectRegistry_doc,
  "key = ConnectRegistry(computer_name, key) - "
  "Establishes a connection to a predefined registry handle on another computer.\n"
***************
*** 89,95 ****
  "\n"
  "The return value is the handle of the opened key.\n"
! "If the function fails, an EnvironmentError exception is raised.";

! static char CreateKey_doc[] =
  "key = CreateKey(key, sub_key) - Creates or opens the specified key.\n"
  "\n"
--- 89,95 ----
  "\n"
  "The return value is the handle of the opened key.\n"
! "If the function fails, an EnvironmentError exception is raised.");

! PyDoc_STRVAR(CreateKey_doc,
  "key = CreateKey(key, sub_key) - Creates or opens the specified key.\n"
  "\n"
***************
*** 102,108 ****
  "\n"
  "The return value is the handle of the opened key.\n"
! "If the function fails, an exception is raised.";

! static char DeleteKey_doc[] =
  "DeleteKey(key, sub_key) - Deletes the specified key.\n"
  "\n"
--- 102,108 ----
  "\n"
  "The return value is the handle of the opened key.\n"
! "If the function fails, an exception is raised.");

! PyDoc_STRVAR(DeleteKey_doc,
  "DeleteKey(key, sub_key) - Deletes the specified key.\n"
  "\n"
***************
*** 114,126 ****
  "\n"
  "If the method succeeds, the entire key, including all of its values,\n"
! "is removed.  If the method fails, an EnvironmentError exception is raised.";

! static char DeleteValue_doc[] =
  "DeleteValue(key, value) - Removes a named value from a registry key.\n"
  "\n"
  "key is an already open key, or any one of the predefined HKEY_* constants.\n"
! "value is a string that identifies the value to remove.";

! static char EnumKey_doc[] =
  "string = EnumKey(key, index) - Enumerates subkeys of an open registry key.\n"
  "\n"
--- 114,126 ----
  "\n"
  "If the method succeeds, the entire key, including all of its values,\n"
! "is removed.  If the method fails, an EnvironmentError exception is raised.");

! PyDoc_STRVAR(DeleteValue_doc,
  "DeleteValue(key, value) - Removes a named value from a registry key.\n"
  "\n"
  "key is an already open key, or any one of the predefined HKEY_* constants.\n"
! "value is a string that identifies the value to remove.");

! PyDoc_STRVAR(EnumKey_doc,
  "string = EnumKey(key, index) - Enumerates subkeys of an open registry key.\n"
  "\n"
***************
*** 130,136 ****
  "The function retrieves the name of one subkey each time it is called.\n"
  "It is typically called repeatedly until an EnvironmentError exception is\n"
! "raised, indicating no more values are available.\n";

! static char EnumValue_doc[] =
  "tuple = EnumValue(key, index) - Enumerates values of an open registry key.\n"
  "key is an already open key, or any one of the predefined HKEY_* constants.\n"
--- 130,136 ----
  "The function retrieves the name of one subkey each time it is called.\n"
  "It is typically called repeatedly until an EnvironmentError exception is\n"
! "raised, indicating no more values are available.");

! PyDoc_STRVAR(EnumValue_doc,
  "tuple = EnumValue(key, index) - Enumerates values of an open registry key.\n"
  "key is an already open key, or any one of the predefined HKEY_* constants.\n"
***************
*** 145,151 ****
  "value_data is an object that holds the value data, and whose type depends\n"
  " on the underlying registry type.\n"
! "data_type is an integer that identifies the type of the value data.";

! static char FlushKey_doc[] =
  "FlushKey(key) - Writes all the attributes of a key to the registry.\n"
  "\n"
--- 145,151 ----
  "value_data is an object that holds the value data, and whose type depends\n"
  " on the underlying registry type.\n"
! "data_type is an integer that identifies the type of the value data.");

! PyDoc_STRVAR(FlushKey_doc,
  "FlushKey(key) - Writes all the attributes of a key to the registry.\n"
  "\n"
***************
*** 158,164 ****
  "been written to the registry.\n"
  "An application should only call FlushKey() if it requires absolute certainty that registry changes are on disk.\n"
! "If you don't know whether a FlushKey() call is required, it probably isn't.\n";

! static char LoadKey_doc[] =
  "LoadKey(key, sub_key, file_name) - Creates a subkey under the specified key\n"
  "and stores registration information from a specified file into that subkey.\n"
--- 158,164 ----
  "been written to the registry.\n"
  "An application should only call FlushKey() if it requires absolute certainty that registry changes are on disk.\n"
! "If you don't know whether a FlushKey() call is required, it probably isn't.");

! PyDoc_STRVAR(LoadKey_doc,
  "LoadKey(key, sub_key, file_name) - Creates a subkey under the specified key\n"
  "and stores registration information from a specified file into that subkey.\n"
***************
*** 177,183 ****
  "in fileName is relative to the remote computer.\n"
  "\n"
! "The docs imply key must be in the HKEY_USER or HKEY_LOCAL_MACHINE tree";

! static char OpenKey_doc[] =
  "key = OpenKey(key, sub_key, res = 0, sam = KEY_READ) - Opens the specified key.\n"
  "\n"
--- 177,183 ----
  "in fileName is relative to the remote computer.\n"
  "\n"
! "The docs imply key must be in the HKEY_USER or HKEY_LOCAL_MACHINE tree");

! PyDoc_STRVAR(OpenKey_doc,
  "key = OpenKey(key, sub_key, res = 0, sam = KEY_READ) - Opens the specified key.\n"
  "\n"
***************
*** 189,198 ****
  "\n"
  "The result is a new handle to the specified key\n"
! "If the function fails, an EnvironmentError exception is raised.\n";

! static char OpenKeyEx_doc[] =
! "See OpenKey()";

! static char QueryInfoKey_doc[] =
  "tuple = QueryInfoKey(key) - Returns information about a key.\n"
  "\n"
--- 189,197 ----
  "\n"
  "The result is a new handle to the specified key\n"
! "If the function fails, an EnvironmentError exception is raised.");

! PyDoc_STRVAR(OpenKeyEx_doc, "See OpenKey()");

! PyDoc_STRVAR(QueryInfoKey_doc,
  "tuple = QueryInfoKey(key) - Returns information about a key.\n"
  "\n"
***************
*** 203,209 ****
  "An integer that identifies the number of values this key has.\n"
  "A long integer that identifies when the key was last modified (if available)\n"
! " as 100's of nanoseconds since Jan 1, 1600.\n";

! static char QueryValue_doc[] =
  "string = QueryValue(key, sub_key) - retrieves the unnamed value for a key.\n"
  "\n"
--- 202,208 ----
  "An integer that identifies the number of values this key has.\n"
  "A long integer that identifies when the key was last modified (if available)\n"
! " as 100's of nanoseconds since Jan 1, 1600.");

! PyDoc_STRVAR(QueryValue_doc,
  "string = QueryValue(key, sub_key) - retrieves the unnamed value for a key.\n"
  "\n"
***************
*** 215,227 ****
  "Values in the registry have name, type, and data components. This method\n"
  "retrieves the data for a key's first value that has a NULL name.\n"
! "But the underlying API call doesn't return the type, Lame Lame Lame, DONT USE THIS!!!";

! static char QueryValueEx_doc[] =
  "value,type_id = QueryValueEx(key, value_name) - Retrieves the type and data for a specified value name associated with an open registry key.\n"
  "\n"
  "key is an already open key, or any one of the predefined HKEY_* constants.\n"
! "value_name is a string indicating the value to query";

! static char SaveKey_doc[] =
  "SaveKey(key, file_name) - Saves the specified key, and all its subkeys to the specified file.\n"
  "\n"
--- 214,226 ----
  "Values in the registry have name, type, and data components. This method\n"
  "retrieves the data for a key's first value that has a NULL name.\n"
! "But the underlying API call doesn't return the type, Lame Lame Lame, DONT USE THIS!!!");

! PyDoc_STRVAR(QueryValueEx_doc,
  "value,type_id = QueryValueEx(key, value_name) - Retrieves the type and data for a specified value name associated with an open registry key.\n"
  "\n"
  "key is an already open key, or any one of the predefined HKEY_* constants.\n"
! "value_name is a string indicating the value to query");

! PyDoc_STRVAR(SaveKey_doc,
  "SaveKey(key, file_name) - Saves the specified key, and all its subkeys to the specified file.\n"
  "\n"
***************
*** 235,241 ****
  "file_name is relative to the remote computer.\n"
  "The caller of this method must possess the SeBackupPrivilege security privilege.\n"
! "This function passes NULL for security_attributes to the API.";

! static char SetValue_doc[] =
  "SetValue(key, sub_key, type, value) - Associates a value with a specified key.\n"
  "\n"
--- 234,240 ----
  "file_name is relative to the remote computer.\n"
  "The caller of this method must possess the SeBackupPrivilege security privilege.\n"
! "This function passes NULL for security_attributes to the API.");

! PyDoc_STRVAR(SetValue_doc,
  "SetValue(key, sub_key, type, value) - Associates a value with a specified key.\n"
  "\n"
***************
*** 254,260 ****
  "\n"
  "The key identified by the key parameter must have been opened with\n"
! "KEY_SET_VALUE access.";

! static char SetValueEx_doc[] =
  "SetValueEx(key, value_name, reserved, type, value) - Stores data in the value field of an open registry key.\n"
  "\n"
--- 253,259 ----
  "\n"
  "The key identified by the key parameter must have been opened with\n"
! "KEY_SET_VALUE access.");

! PyDoc_STRVAR(SetValueEx_doc,
  "SetValueEx(key, value_name, reserved, type, value) - Stores data in the value field of an open registry key.\n"
  "\n"
***************
*** 286,293 ****
  "Value lengths are limited by available memory. Long values (more than\n"
  "2048 bytes) should be stored as files with the filenames stored in \n"
! "the configuration registry.  This helps the registry perform efficiently.\n";

  /* PyHKEY docstrings */
! static char PyHKEY_doc[] =
  "PyHKEY Object - A Python object, representing a win32 registry key.\n"
  "\n"
--- 285,292 ----
  "Value lengths are limited by available memory. Long values (more than\n"
  "2048 bytes) should be stored as files with the filenames stored in \n"
! "the configuration registry.  This helps the registry perform efficiently.");

  /* PyHKEY docstrings */
! PyDoc_STRVAR(PyHKEY_doc,
  "PyHKEY Object - A Python object, representing a win32 registry key.\n"
  "\n"
***************
*** 309,321 ****
  "__nonzero__ - Handles with an open object return true, otherwise false.\n"
  "__int__ - Converting a handle to an integer returns the Win32 handle.\n"
! "__cmp__ - Handle objects are compared using the handle value.\n";

! static char PyHKEY_Close_doc[] =
  "key.Close() - Closes the underlying Windows handle.\n"
  "\n"
! "If the handle is already closed, no error is raised.";

! static char PyHKEY_Detach_doc[] =
  "int = key.Detach() - Detaches the Windows handle from the handle object.\n"
  "\n"
--- 308,320 ----
  "__nonzero__ - Handles with an open object return true, otherwise false.\n"
  "__int__ - Converting a handle to an integer returns the Win32 handle.\n"
! "__cmp__ - Handle objects are compared using the handle value.");

! PyDoc_STRVAR(PyHKEY_Close_doc,
  "key.Close() - Closes the underlying Windows handle.\n"
  "\n"
! "If the handle is already closed, no error is raised.");

! PyDoc_STRVAR(PyHKEY_Detach_doc,
  "int = key.Detach() - Detaches the Windows handle from the handle object.\n"
  "\n"
***************
*** 327,331 ****
  "need the underlying win32 handle to exist beyond the lifetime of the\n"
  "handle object.\n"
! "On 64 bit windows, the result of this function is a long integer\n";

--- 326,330 ----
  "need the underlying win32 handle to exist beyond the lifetime of the\n"
  "handle object.\n"
! "On 64 bit windows, the result of this function is a long integer");

Index: winsound.c
===================================================================
RCS file: /cvsroot/python/python/dist/src/PC/winsound.c,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** winsound.c	31 Mar 2002 14:37:44 -0000	1.9
--- winsound.c	13 Jun 2002 20:33:02 -0000	1.10
***************
*** 41,51 ****
  #include <Python.h>

! static char sound_playsound_doc[] =
  "PlaySound(sound, flags) - a wrapper around the Windows PlaySound API\n"
  "\n"
  "The sound argument can be a filename, data, or None.\n"
! "For flag values, ored together, see module documentation.\n";

! static char sound_beep_doc[] =
  "Beep(frequency, duration) - a wrapper around the Windows Beep API\n"
  "\n"
--- 41,51 ----
  #include <Python.h>

! PyDoc_STRVAR(sound_playsound_doc,
  "PlaySound(sound, flags) - a wrapper around the Windows PlaySound API\n"
  "\n"
  "The sound argument can be a filename, data, or None.\n"
! "For flag values, ored together, see module documentation.");

! PyDoc_STRVAR(sound_beep_doc,
  "Beep(frequency, duration) - a wrapper around the Windows Beep API\n"
  "\n"
***************
*** 55,61 ****
  "On WinNT and 2000, the platform Beep API is used directly.  Else funky\n"
  "code doing direct port manipulation is used; it's unknown whether that\n"
! "will work on all systems.\n";

! static char sound_module_doc[] =
  "PlaySound(sound, flags) - play a sound\n"
  "SND_FILENAME - sound is a wav file name\n"
--- 55,61 ----
  "On WinNT and 2000, the platform Beep API is used directly.  Else funky\n"
  "code doing direct port manipulation is used; it's unknown whether that\n"
! "will work on all systems.");

! PyDoc_STRVAR(sound_module_doc,
  "PlaySound(sound, flags) - play a sound\n"
  "SND_FILENAME - sound is a wav file name\n"
***************
*** 69,73 ****
  "SND_NOWAIT - Return immediately if the sound driver is busy\n" // Without any errors
  "\n"
! "Beep(frequency, duration) - Make a beep through the PC speaker.\n";

  PyObject *
--- 69,73 ----
  "SND_NOWAIT - Return immediately if the sound driver is busy\n" // Without any errors
  "\n"
! "Beep(frequency, duration) - Make a beep through the PC speaker.");

  PyObject *