added some documentation

git-svn-id: svn://svn.code.sf.net/p/processhacker/code@4070 21ef857c-d57f-4fe0-8362-d861dc6d29cd

2.x/trunk/ProcessHacker/anawait.c

@@ -890,8 +890,8 @@ static PPH_STRING PhapGetSendMessageReceiver(
 
     threadId = GetWindowThreadProcessId(windowHandle, &processId);
 
-    clientId.UniqueProcess = UlongToPtr(processId);
-    clientId.UniqueThread = UlongToPtr(threadId);
+    clientId.UniqueProcess = UlongToHandle(processId);
+    clientId.UniqueThread = UlongToHandle(threadId);
     clientIdName = PHA_DEREFERENCE(PhGetClientIdName(&clientId));
 
     return PhaFormatString(L"Window 0x%Ix (%s)", windowHandle, clientIdName->Buffer);

2.x/trunk/ProcessHacker/appsup.c

@@ -26,6 +26,12 @@
 #include <winsta.h>
 #include <dbghelp.h>
 
+/**
+ * Determines whether a process is suspended.
+ *
+ * \param Process The SYSTEM_PROCESS_INFORMATION structure 
+ * of the process.
+ */
 BOOLEAN PhGetProcessIsSuspended(
     __in PSYSTEM_PROCESS_INFORMATION Process
     )
@@ -44,6 +50,13 @@ BOOLEAN PhGetProcessIsSuspended(
     return Process->NumberOfThreads != 0;
 }
 
+/**
+ * Determines the type of a process based on its image file name.
+ *
+ * \param ProcessHandle A handle to a process.
+ * \param KnownProcessType A variable which receives the process 
+ * type.
+ */
 NTSTATUS PhGetProcessKnownType(
     __in HANDLE ProcessHandle,
     __out PH_KNOWN_PROCESS_TYPE *KnownProcessType
@@ -582,6 +595,14 @@ PWSTR PhMakeContextAtom()
     PH_DEFINE_MAKE_ATOM(L"PH2_Context");
 }
 
+/**
+ * Copies a string into a NMLVGETINFOTIP structure.
+ *
+ * \param GetInfoTip The NMLVGETINFOTIP structure.
+ * \param Tip The string to copy.
+ *
+ * \remarks The text is truncated if it is too long.
+ */
 VOID PhCopyListViewInfoTip(
     __inout LPNMLVGETINFOTIP GetInfoTip,
     __in PPH_STRINGREF Tip

2.x/trunk/ProcessHacker/procprv.c

@@ -406,6 +406,9 @@ PWSTR PhGetProcessPriorityClassString(
     }
 }
 
+/**
+ * Creates a process item.
+ */
 PPH_PROCESS_ITEM PhCreateProcessItem(
     __in HANDLE ProcessId
     )
@@ -495,6 +498,15 @@ FORCEINLINE ULONG PhHashProcessItem(
     return (ULONG)Value->ProcessId / 4;
 }
 
+/**
+ * Finds a process item in the hash set.
+ *
+ * \param ProcessId The process ID of the process item.
+ *
+ * \remarks The hash set must be locked before calling this 
+ * function. The reference count of the found process item is 
+ * not incremented.
+ */
 __assumeLocked PPH_PROCESS_ITEM PhpLookupProcessItem(
     __in HANDLE ProcessId
     )
@@ -521,6 +533,13 @@ __assumeLocked PPH_PROCESS_ITEM PhpLookupProcessItem(
     return NULL;
 }
 
+/**
+ * Finds and references a process item.
+ *
+ * \param ProcessId The process ID of the process item.
+ *
+ * \return The found process item.
+ */
 PPH_PROCESS_ITEM PhReferenceProcessItem(
     __in HANDLE ProcessId
     )
@@ -539,6 +558,15 @@ PPH_PROCESS_ITEM PhReferenceProcessItem(
     return processItem;
 }
 
+/**
+ * Enumerates the process items.
+ *
+ * \param ProcessItems A variable which receives an array of 
+ * pointers to process items. You must free the buffer with 
+ * PhFree() when you no longer need it.
+ * \param NumberOfProcessItems A variable which receives the 
+ * number of process items returned in \a ProcessItems.
+ */
 VOID PhEnumProcessItems(
     __out_opt PPH_PROCESS_ITEM **ProcessItems,
     __out PULONG NumberOfProcessItems
@@ -611,6 +639,21 @@ INT NTAPI PhpVerifyCacheCompareFunction(
     return PhCompareString(entry1->FileName, entry2->FileName, TRUE);
 }
 
+/**
+ * Verifies a file's digital signature, using a cached 
+ * result if possible.
+ *
+ * \param FileName A file name.
+ * \param SignerName A variable which receives a pointer 
+ * to a string containing the signer name. You must free 
+ * the string using PhDereferenceObject() when you no 
+ * longer need it. Note that the signer name may be NULL 
+ * if it is not valid.
+ * \param CachedOnly Specify TRUE to fail the function when 
+ * no cached result exists.
+ *
+ * \return A VERIFY_RESULT value.
+ */
 VERIFY_RESULT PhVerifyFileCached(
     __in PPH_STRING FileName,
     __out_opt PPH_STRING *SignerName,
@@ -1374,6 +1417,18 @@ VOID PhpUpdateSystemHistory()
     PhTimeSequenceNumber++;
 }
 
+/**
+ * Retrieves a time value recorded by the statistics system.
+ *
+ * \param ProcessItem A process item to synchronize with, or NULL if 
+ * no synchronization is necessary.
+ * \param Index The history index.
+ * \param Time A variable which receives the time at \a Index.
+ *
+ * \return TRUE if the function succeeded, otherwise FALSE if 
+ * \a ProcessItem was specified and \a Index is too far into the 
+ * past for that process item.
+ */
 BOOLEAN PhGetStatisticsTime(
     __in_opt PPH_PROCESS_ITEM ProcessItem,
     __in ULONG Index,
@@ -2233,6 +2288,9 @@ PPH_PROCESS_RECORD PhFindProcessRecord(
         return NULL;
 }
 
+/**
+ * Deletes unused process records.
+ */
 VOID PhPurgeProcessRecords()
 {
     PPH_PROCESS_RECORD processRecord;

2.x/trunk/phlib/error.c

@@ -22,6 +22,12 @@
 
 #include <phbase.h>
 
+/**
+ * Converts a NTSTATUS value to a Win32 error code.
+ *
+ * \remarks This function handles FACILITY_NTWIN32 status values 
+ * properly, unlike RtlNtStatusToDosError.
+ */
 ULONG PhNtStatusToDosError(
     __in NTSTATUS Status
     )
@@ -32,6 +38,12 @@ ULONG PhNtStatusToDosError(
         return RtlNtStatusToDosError(Status);
 }
 
+/**
+ * Converts a Win32 error code to a NTSTATUS value.
+ *
+ * \remarks Only a small number of cases are currently supported. 
+ * Other status values are wrapped using FACILITY_NTWIN32.
+ */
 NTSTATUS PhDosErrorToNtStatus(
     __in ULONG DosError
     )
@@ -54,6 +66,10 @@ NTSTATUS PhDosErrorToNtStatus(
     }
 }
 
+/**
+ * Determines whether a NTSTATUS value indicates that a file 
+ * cannot be not found.
+ */
 BOOLEAN PhNtStatusFileNotFound(
     __in NTSTATUS Status
     )

2.x/trunk/phlib/extlv.c

@@ -126,6 +126,11 @@ static PWSTR PhpMakeExtLvContextAtom()
     PH_DEFINE_MAKE_ATOM(L"PhLib_ExtLvContext");
 }
 
+/**
+ * Enables extended list view support for a list view control.
+ *
+ * \param hWnd A handle to the list view control.
+ */
 VOID PhSetExtendedListView(
     __in HWND hWnd
     )
@@ -708,6 +713,13 @@ LRESULT CALLBACK PhpExtendedListViewWndProc(
     return CallWindowProc(oldWndProc, hwnd, uMsg, wParam, lParam);
 }
 
+/**
+ * Visually indicates the sort order of a header control item.
+ *
+ * \param hwnd A handle to the header control.
+ * \param Index The index of the item.
+ * \param Order The sort order of the item.
+ */
 VOID PhSetHeaderSortIcon(
     __in HWND hwnd,
     __in INT Index,

2.x/trunk/phlib/format.c

@@ -69,6 +69,14 @@ static WCHAR PhpFormatDecimalSeparator = '.';
 static WCHAR PhpFormatThousandSeparator = ',';
 static _locale_t PhpFormatUserLocale = NULL;
 
+/**
+ * Converts an ANSI string to a Unicode string by zero-extending 
+ * each byte.
+ *
+ * \param Input The original ANSI string.
+ * \param InputLength The length of \a Input.
+ * \param Output A buffer which will contain the converted string.
+ */
 VOID PhZeroExtendToUnicode(
     __in_bcount(InputLength) PSTR Input,
     __in ULONG InputLength,

2.x/trunk/phlib/graph.c

@@ -73,6 +73,12 @@ BOOLEAN PhGraphControlInitialization()
     return TRUE;
 }
 
+/**
+ * Draws a graph.
+ *
+ * \param hdc The DC to draw to.
+ * \param DrawInfo A structure which contains graphing information.
+ */
 VOID PhDrawGraph(
     __in HDC hdc,
     __in PPH_GRAPH_DRAW_INFO DrawInfo
@@ -333,6 +339,18 @@ VOID PhDrawGraph(
     }
 }
 
+/**
+ * Sets the text in a graphing information structure.
+ *
+ * \param hdc The DC to perform calculations from.
+ * \param DrawInfo A structure which contains graphing information. 
+ * The structure is modified to contain the new text information.
+ * \param Text The text.
+ * \param Margin The margins of the text box from the edges of the 
+ * graph.
+ * \param Padding The padding within the text box.
+ * \param Align The alignment of the text box.
+ */
 VOID PhSetGraphText(
     __in HDC hdc,
     __inout PPH_GRAPH_DRAW_INFO DrawInfo,
@@ -875,6 +893,11 @@ LRESULT CALLBACK PhpGraphWndProc(
     return DefWindowProc(hwnd, uMsg, wParam, lParam);
 }
 
+/**
+ * Initializes a graph buffer management structure.
+ *
+ * \param Buffers The buffer management structure.
+ */
 VOID PhInitializeGraphBuffers(
     __out PPH_GRAPH_BUFFERS Buffers
     )
@@ -885,6 +908,11 @@ VOID PhInitializeGraphBuffers(
     Buffers->Valid = FALSE;
 }
 
+/**
+ * Frees resources used by a graph buffer management structure.
+ *
+ * \param Buffers The buffer management structure.
+ */
 VOID PhDeleteGraphBuffers(
     __inout PPH_GRAPH_BUFFERS Buffers
     )
@@ -893,6 +921,15 @@ VOID PhDeleteGraphBuffers(
     if (Buffers->Data2) PhFree(Buffers->Data2);
 }
 
+/**
+ * Sets up a graphing information structure with information 
+ * from a graph buffer management structure.
+ *
+ * \param Buffers The buffer management structure.
+ * \param DrawInfo The graphing information structure.
+ * \param DataCount The number of data points currently required. 
+ * The buffers are resized if needed.
+ */
 VOID PhGetDrawInfoGraphBuffers(
     __inout PPH_GRAPH_BUFFERS Buffers,
     __inout PPH_GRAPH_DRAW_INFO DrawInfo,

2.x/trunk/phlib/secdata.c

@@ -597,6 +597,17 @@ static PH_SPECIFIC_TYPE PhSpecificTypes[] =
     ACCESS_ENTRY(WmiGuid, TRUE)
 };
 
+/**
+ * Gets access entries for an object type.
+ *
+ * \param Type The name of the object type.
+ * \param AccessEntries A variable which receives an array of 
+ * access entry structures. You must free the buffer with 
+ * PhFree() when you no longer need it.
+ * \param NumberOfAccessEntries A variable which receives 
+ * the number of access entry structures returned in 
+ * \a AccessEntries.
+ */
 BOOLEAN PhGetAccessEntries(
     __in PWSTR Type,
     __out PPH_ACCESS_ENTRY *AccessEntries,
@@ -697,6 +708,17 @@ static int __cdecl PhpAccessEntryCompare(
     return intcmp(PhCountBits(entry2->Access), PhCountBits(entry1->Access));
 }
 
+/**
+ * Creates a string representation of an access mask.
+ *
+ * \param Access The access mask.
+ * \param AccessEntries An array of access entry structures. You can 
+ * call PhGetAccessEntries() to retrieve the access entry structures 
+ * for a standard object type.
+ * \param NumberOfAccessEntries The number of elements in \a AccessEntries.
+ *
+ * \return The string representation of \a Access.
+ */
 PPH_STRING PhGetAccessString(
     __in ACCESS_MASK Access,
     __in PPH_ACCESS_ENTRY AccessEntries,