Documentation update.

dlls/kernel/debugger.c

@@ -19,15 +19,16 @@ DEFAULT_DEBUG_CHANNEL(debugstr);
 /******************************************************************************
  *           WaitForDebugEvent   (KERNEL32.720)
  *
- * Waits for a debugging event to occur in a process being debugged
+ *  Waits for a debugging event to occur in a process being debugged before
+ *  filling out the debug event structure.
  *
- * PARAMS
- *    event   [I] Address of structure for event information
- *    timeout [I] Number of milliseconds to wait for event
+ * RETURNS
  *
- * RETURNS STD
+ *  Returns true if a debug event occurred and false if the call timed out.
  */
-BOOL WINAPI WaitForDebugEvent( LPDEBUG_EVENT event, DWORD timeout )
+BOOL WINAPI WaitForDebugEvent(
+	 LPDEBUG_EVENT event, /* Address of structure for event information. */
+	 DWORD timeout /* Number of milliseconds to wait for event. */)
 {
     BOOL ret;
     SERVER_START_REQ
@@ -111,8 +112,18 @@ BOOL WINAPI WaitForDebugEvent( LPDEBUG_EVENT event, DWORD timeout )
 
 /**********************************************************************
  *           ContinueDebugEvent   (KERNEL32.146)
+ *
+ *  Enables a thread that previously produced a debug event to continue.
+ *
+ * RETURNS
+ *
+ *  True if the debugger is listed as the processes owner and the process
+ *  and thread are valid.
  */
-BOOL WINAPI ContinueDebugEvent( DWORD pid, DWORD tid, DWORD status )
+BOOL WINAPI ContinueDebugEvent(
+	DWORD pid, /* The id of the process to continue. */
+	DWORD tid, /* The id of the thread to continue. */
+	DWORD status /* The rule to apply to unhandled exeptions. */)
 {
     BOOL ret;
     SERVER_START_REQ
@@ -130,8 +141,15 @@ BOOL WINAPI ContinueDebugEvent( DWORD pid, DWORD tid, DWORD status )
 
 /**********************************************************************
  *           DebugActiveProcess   (KERNEL32.180)
+ *
+ *  Attempts to attach the dugger to a process.
+ *
+ * RETURNS
+ *
+ *  True if the debugger was attached to process.
  */
-BOOL WINAPI DebugActiveProcess( DWORD pid )
+BOOL WINAPI DebugActiveProcess(
+	DWORD pid /* The process to be debugged. */)
 {
     BOOL ret;
     SERVER_START_REQ
@@ -147,8 +165,12 @@ BOOL WINAPI DebugActiveProcess( DWORD pid )
 
 /***********************************************************************
  *           OutputDebugStringA   (KERNEL32.548)
+ *
+ *  Output by an application of a unicode string to a debugger (if attached)
+ *  and program log.
  */
-void WINAPI OutputDebugStringA( LPCSTR str )
+void WINAPI OutputDebugStringA(
+        LPCSTR str /* The message to be logged and given to the debugger. */)
 {
     SERVER_START_REQ
     {
@@ -165,8 +187,12 @@ void WINAPI OutputDebugStringA( LPCSTR str )
 
 /***********************************************************************
  *           OutputDebugStringW   (KERNEL32.549)
+ *
+ *  Output by an appliccation of a unicode string to a debugger (if attached)
+ *  and program log.
  */
-void WINAPI OutputDebugStringW( LPCWSTR str )
+void WINAPI OutputDebugStringW(
+	LPCWSTR str /* The message to be logged and given to the debugger. */)
 {
     SERVER_START_REQ
     {
@@ -183,8 +209,12 @@ void WINAPI OutputDebugStringW( LPCWSTR str )
 
 /***********************************************************************
  *           OutputDebugString16   (KERNEL.115)
+ *
+ *  Output by a 16 bit application of an ascii string to a debugger (if attached)
+ *  and program log.
  */
-void WINAPI OutputDebugString16( LPCSTR str )
+void WINAPI OutputDebugString16(
+        LPCSTR str /* The message to be logged and given to the debugger.*/)
 {
     OutputDebugStringA( str );
 }
@@ -192,6 +222,9 @@ void WINAPI OutputDebugString16( LPCSTR str )
 
 /***********************************************************************
  *           DebugBreak   (KERNEL32.181)
+ *
+ *  Raises an exception so that a debugger (if attached)
+ *  can take some action.
  */
 void WINAPI DebugBreak(void)
 {
@@ -201,8 +234,16 @@ void WINAPI DebugBreak(void)
 
 /***********************************************************************
  *           DebugBreak16   (KERNEL.203)
+ *
+ *  Raises an expection in a 16 bit application so that a debugger (if attached)
+ *  can take some action.
+ *
+ * BUGS
+ *
+ *  Only 386 compatible processors implemented.
  */
-void WINAPI DebugBreak16( CONTEXT86 *context )
+void WINAPI DebugBreak16(
+        CONTEXT86 *context /* A pointer to the 386 compatible processor state. */)
 {
 #ifdef __i386__
     EXCEPTION_RECORD rec;
@@ -219,6 +260,12 @@ void WINAPI DebugBreak16( CONTEXT86 *context )
 
 /***********************************************************************
  *           IsDebuggerPresent   (KERNEL32)
+ *
+ *  Allows a process to determine if there is a debugger attached.
+ *
+ * RETURNS
+ *
+ *  True if there is a debugger attached.
  */
 BOOL WINAPI IsDebuggerPresent(void)
 {

dlls/kernel/time.c

@@ -33,10 +33,15 @@ static int TIME_GetBias( time_t utc, int *pdaylight)
 /***********************************************************************
  *              SetLocalTime            (KERNEL32.655)
  *
- * FIXME: correct ? Is the timezone param of settimeofday() needed ?
- * I don't have any docu about SetLocal/SystemTime(), argl...
+ *  Sets the local time using current time zone and daylight
+ *  savings settings.
+ *
+ * RETURNS
+ *
+ *  True if the time was set, false if the time was invalid or the
+ *  necessary permissions were not held.
  */
-BOOL WINAPI SetLocalTime(const SYSTEMTIME *systime)
+BOOL WINAPI SetLocalTime( const SYSTEMTIME *systime /* The desired local time. */ )
 {
     struct timeval tv;
     struct tm t;
@@ -80,10 +85,22 @@ BOOL WINAPI SetLocalTime(const SYSTEMTIME *systime)
 /***********************************************************************
  *           GetSystemTimeAdjustment     (KERNEL32.407)
  *
+ *  Indicates the period between clock interrupt and the amount the clock
+ *  is adjusted each interrupt so as to keep it insync with an external source.
+ *
+ * RETURNS
+ *
+ *  Always returns true.
+ *
+ * BUGS
+ *
+ *  Only the special case of disabled time adjustments is supported.
+ *  (also the signature is wrong it should have a return type of BOOL)
  */
-DWORD WINAPI GetSystemTimeAdjustment( LPDWORD lpTimeAdjustment,
-                                      LPDWORD lpTimeIncrement,
-                                      LPBOOL lpTimeAdjustmentDisabled )
+DWORD WINAPI GetSystemTimeAdjustment(
+	 LPDWORD lpTimeAdjustment, /* The clock adjustment per interupt in 100's of nanoseconds. */
+	 LPDWORD lpTimeIncrement, /* The time between clock interupts in 100's of nanoseconds. */
+	 LPBOOL lpTimeAdjustmentDisabled /* The clock synchonisation has been disabled. */ )
 {
     *lpTimeAdjustment = 0;
     *lpTimeIncrement = 0;
@@ -94,8 +111,16 @@ DWORD WINAPI GetSystemTimeAdjustment( LPDWORD lpTimeAdjustment,
 
 /***********************************************************************
  *              SetSystemTime            (KERNEL32.507)
+ *
+ *  Sets the system time (utc).
+ *
+ * RETURNS
+ *
+ *  True if the time was set, false if the time was invalid or the
+ *  necessary permissions were not held.
  */
-BOOL WINAPI SetSystemTime(const SYSTEMTIME *systime)
+BOOL WINAPI SetSystemTime(
+    const SYSTEMTIME *systime /* The desired system time. */)
 {
     struct timeval tv;
     struct timezone tz;
@@ -147,8 +172,16 @@ BOOL WINAPI SetSystemTime(const SYSTEMTIME *systime)
 
 /***********************************************************************
  *              GetTimeZoneInformation  (KERNEL32.302)
+ *
+ *  Fills in the a time zone information structure with values based on
+ *  the current local time.
+ *
+ * RETURNS
+ *
+ *  The daylight savings time standard or TIME_ZONE_ID_INVALID if the call failed.
  */
-DWORD WINAPI GetTimeZoneInformation(LPTIME_ZONE_INFORMATION tzinfo)
+DWORD WINAPI GetTimeZoneInformation(
+	LPTIME_ZONE_INFORMATION tzinfo /* The time zone structure to be filled in. */)
 {
     time_t gmt;
     int bias, daylight;
@@ -168,8 +201,19 @@ DWORD WINAPI GetTimeZoneInformation(LPTIME_ZONE_INFORMATION tzinfo)
 
 /***********************************************************************
  *              SetTimeZoneInformation  (KERNEL32.515)
+ *
+ *  Set the local time zone with values based on the time zone structure.
+ *
+ * RETURNS
+ *
+ *  True on successful setting of the time zone.
+ *
+ * BUGS
+ *
+ *  Use the obsolete unix timezone structure and tz_dsttime member.
  */
-BOOL WINAPI SetTimeZoneInformation(const LPTIME_ZONE_INFORMATION tzinfo)
+BOOL WINAPI SetTimeZoneInformation(
+	const LPTIME_ZONE_INFORMATION tzinfo /* The new time zone. */)
 {
     struct timezone tz;
 
@@ -185,11 +229,21 @@ BOOL WINAPI SetTimeZoneInformation(const LPTIME_ZONE_INFORMATION tzinfo)
 
 /***********************************************************************
  *              SystemTimeToTzSpecificLocalTime  (KERNEL32.683)
+ *
+ *  Converts the system time (utc) to the local time in the specified time zone.
+ *
+ * RETURNS
+ *
+ *  Returns true when the local time was calculated.
+ *
+ * BUGS
+ *
+ *  Does not handle daylight savings time adjustments correctly.
  */
 BOOL WINAPI SystemTimeToTzSpecificLocalTime(
-  LPTIME_ZONE_INFORMATION lpTimeZoneInformation,
-  LPSYSTEMTIME lpUniversalTime,
-  LPSYSTEMTIME lpLocalTime)
+	LPTIME_ZONE_INFORMATION lpTimeZoneInformation, /* The desired time zone. */
+	LPSYSTEMTIME lpUniversalTime, /* The utc time to base local time on. */
+	LPSYSTEMTIME lpLocalTime /* The local time in the time zone. */)
 {
   FIXME(":stub\n");
   SetLastError(ERROR_CALL_NOT_IMPLEMENTED);
@@ -199,18 +253,21 @@ BOOL WINAPI SystemTimeToTzSpecificLocalTime(
 
 /***********************************************************************
  *              GetSystemTimeAsFileTime  (KERNEL32)
+ *
+ *  Fills in a file time structure with the current time in UTC format.
  */
-VOID WINAPI GetSystemTimeAsFileTime( LPFILETIME time )
+VOID WINAPI GetSystemTimeAsFileTime(
+	LPFILETIME time /* The file time struct to be filled with the system time. */)
 {
     NtQuerySystemTime( (LARGE_INTEGER *)time );
 }
 
 
 /*********************************************************************
- *      TIME_ClockTimeToFileTime
- *      (olorin@fandra.org, 20-Sep-1998)
- *      Converts clock_t into FILETIME.
- *      Used by GetProcessTime.
+ *      TIME_ClockTimeToFileTime    (olorin@fandra.org, 20-Sep-1998)
+ *
+ *  Used by GetProcessTimes to convert clock_t into FILETIME.
+ *
  *      Differences to UnixTimeToFileTime:
  *          1) Divided by CLK_TCK
  *          2) Time is relative. There is no 'starting date', so there is 
@@ -225,14 +282,27 @@ static void TIME_ClockTimeToFileTime(clock_t unix_time, LPFILETIME filetime)
 /*********************************************************************
  *	GetProcessTimes				[KERNEL32.262]
  *
- * FIXME: lpCreationTime, lpExitTime are NOT INITIALIZED.
- * olorin@fandra.org: Would be nice to substract the cpu time,
- *                    used by Wine at startup.
- *                    Also, there is a need to separate times
- *                    used by different applications.
+ *  Returns the user and kernel execution times of a process,
+ *  along with the creation and exit times if known.
+ *
+ *  olorin@fandra.org:
+ *  Would be nice to subtract the cpu time, used by Wine at startup.
+ *  Also, there is a need to separate times used by different applications.
+ *
+ * RETURNS
+ *
+ *  Always returns true.
+ *
+ * BUGS
+ *
+ *  lpCreationTime, lpExitTime are NOT INITIALIZED.
  */
-BOOL WINAPI GetProcessTimes( HANDLE hprocess,LPFILETIME lpCreationTime,LPFILETIME lpExitTime,
-                             LPFILETIME lpKernelTime, LPFILETIME lpUserTime )
+BOOL WINAPI GetProcessTimes(
+	HANDLE hprocess, /* The process to be queried (obtained from PROCESS_QUERY_INFORMATION). */
+	LPFILETIME lpCreationTime, /* The creation time of the process. */
+	LPFILETIME lpExitTime, /* The exit time of the process if exited. */
+	LPFILETIME lpKernelTime, /* The time spent in kernal routines in 100's of nanoseconds. */
+	LPFILETIME lpUserTime /* The time spent in user routines in 100's of nanoseconds. */)
 {
     struct tms tms;