[AUDIT]

- Add proper function headers, including links to documentation
- All exported functions have publically-available information sources
- The only internal function is actually quite self-explanatory by its name
- Implementation is partly wrong as pointed by Gunnar

svn path=/trunk/; revision=22671

diff --git a/reactos/ntoskrnl/ex/atom.c b/reactos/ntoskrnl/ex/atom.c
index ae6fd39..541de68 100644 (file)
--- a/reactos/ntoskrnl/ex/atom.c
+++ b/reactos/ntoskrnl/ex/atom.c
@@ -1,6 +1,6 @@
 /*\r
- * COPYRIGHT:       See COPYING in the top level directory\r
- * PROJECT:         ReactOS kernel\r
+ * PROJECT:         ReactOS Kernel\r
+ * COPYRIGHT:       GPL - See COPYING in the top level directory\r
  * FILE:            ntoskrnl/ex/atom.c\r
  * PURPOSE:         Executive Atom Functions\r
  * PROGRAMMERS:     Alex Ionescu (alex@relsoft.net)\r
@@ -28,6 +28,17 @@ PRTL_ATOM_TABLE GlobalAtomTable;
 \r
 /* PRIVATE FUNCTIONS *********************************************************/\r
 \r
+/*++\r
+ * @name ExpGetGlobalAtomTable\r
+ *\r
+ * Gets pointer to a global atom table, creates it if not already created\r
+ *\r
+ * @return Pointer to the RTL_ATOM_TABLE, or NULL if it's impossible\r
+ *         to create atom table\r
+ *\r
+ * @remarks Internal function\r
+ *\r
+ *--*/\r
 PRTL_ATOM_TABLE\r
 NTAPI\r
 ExpGetGlobalAtomTable(VOID)\r
@@ -49,9 +60,29 @@ ExpGetGlobalAtomTable(VOID)
 \r
 /* FUNCTIONS ****************************************************************/\r
 \r
-/*\r
+/*++\r
+ * @name NtAddAtom\r
  * @implemented\r
- */\r
+ *\r
+ * Function NtAddAtom creates new Atom in Global Atom Table. If Atom\r
+ * with the same name already exist, internal Atom counter is incremented.\r
+ * See: http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/Atoms/NtAddAtom.html\r
+ *\r
+ * @param AtomName\r
+ *        Atom name in Unicode\r
+ *\r
+ * @param AtomNameLength\r
+ *        Length of the atom name\r
+ *\r
+ * @param Atom\r
+ *        Pointer to RTL_ATOM\r
+ *\r
+ * @return STATUS_SUCCESS in case of success, proper error code\r
+ *         othwerwise.\r
+ *\r
+ * @remarks None\r
+ *\r
+ *--*/\r
 NTSTATUS\r
 NTAPI\r
 NtAddAtom(IN PWSTR AtomName,\r
@@ -151,9 +182,24 @@ NtAddAtom(IN PWSTR AtomName,
     return Status;\r
 }\r
 \r
-/*\r
+/*++\r
+ * @name NtDeleteAtom\r
  * @implemented\r
- */\r
+ *\r
+ * Removes Atom from Global Atom Table. If Atom's reference counter\r
+ * is greater then 1, function decrements this counter, but Atom\r
+ * stayed in Global Atom Table.\r
+ * See: http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/Atoms/NtDeleteAtom.html\r
+ *\r
+ * @param Atom\r
+ *        Atom identifier\r
+ *\r
+ * @return STATUS_SUCCESS in case of success, proper error code\r
+ *         othwerwise.\r
+ *\r
+ * @remarks None\r
+ *\r
+ *--*/\r
 NTSTATUS\r
 NTAPI\r
 NtDeleteAtom(IN RTL_ATOM Atom)\r
@@ -168,9 +214,29 @@ NtDeleteAtom(IN RTL_ATOM Atom)
     return RtlDeleteAtomFromAtomTable(AtomTable, Atom);\r
 }\r
 \r
-/*\r
+/*++\r
+ * @name NtFindAtom\r
  * @implemented\r
- */\r
+ *\r
+ * Retrieves existing Atom's identifier without incrementing Atom's\r
+ * internal counter\r
+ * See: http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/Atoms/NtFindAtom.html\r
+ *\r
+ * @param AtomName\r
+ *        Atom name in Unicode\r
+ *\r
+ * @param AtomNameLength\r
+ *        Length of the atom name\r
+ *\r
+ * @param Atom\r
+ *        Pointer to RTL_ATOM\r
+ *\r
+ * @return STATUS_SUCCESS in case of success, proper error code\r
+ *         othwerwise.\r
+ *\r
+ * @remarks None\r
+ *\r
+ *--*/\r
 NTSTATUS\r
 NTAPI\r
 NtFindAtom(IN PWSTR AtomName,\r
@@ -270,9 +336,36 @@ NtFindAtom(IN PWSTR AtomName,
     return Status;\r
 }\r
 \r
-/*\r
+/*++\r
+ * @name NtQueryInformationAtom\r
  * @implemented\r
- */\r
+ *\r
+ * Gets single Atom properties or reads Global Atom Table\r
+ * See: http://undocumented.ntinternals.net/UserMode/Undocumented%20Functions/Atoms/NtQueryInformationAtom.html\r
+ *\r
+ * @param Atom\r
+ *        Atom to query. If AtomInformationClass parameter is\r
+ *        AtomTableInformation, Atom parameter is not used.\r
+ *\r
+ * @param AtomInformationClass\r
+ *        See ATOM_INFORMATION_CLASS enumeration type for details\r
+ *\r
+ * @param AtomInformation\r
+ *        Result of call - pointer to user's allocated buffer for data\r
+ *\r
+ * @param AtomInformationLength\r
+ *        Size of AtomInformation buffer, in bytes\r
+ *\r
+ * @param ReturnLength\r
+ *        Pointer to ULONG value containing required AtomInformation\r
+ *        buffer size\r
+ *\r
+ * @return STATUS_SUCCESS in case of success, proper error code\r
+ *         othwerwise.\r
+ *\r
+ * @remarks None\r
+ *\r
+ *--*/\r
 NTSTATUS\r
 NTAPI\r
 NtQueryInformationAtom(RTL_ATOM Atom,\r