Question about replacing a stub...

[Joshua Walker]

Hi all.
     On my ever winding quest to fill in the win32 API
documentation, I have found, I think, an intresting
issue.
     When the documentation is generated with
c2man.pl, it checks the .spec file to see if the
function is a stub or not. The problem is that if it
is a stub, no documentation will be generated for that
API. I've decieded to take it upon myself to "fill in
the blankes" as it were, but I need to know if I'm
doing this correctly.

For my example I'm going to use the stubbed function
"AdjustTokenGroups" that is found in avdapi32.dll.

The fist thing I did was update the .spec file so
c2man.pl will parse the function correctly.

I changed
@ stub AdjustTokenGroups

to:
@ stdcall AdjustTokenGroups (long long ptr long ptr
ptr)


That allows c2man to parse the function. So now all I
need to do is add that function to security.c. I added
the following.
---------------------
/******************************************************
 * AdjustTokenGroups [ADVAPI32.@]
 *
 * Adjust the group privileges of an open token
handle.
 *
 */

BOOL WINAPI
  AdjustTokenGroups(
  HANDLE TokenHandle,
  BOOL ResetToDefault,
  PTOKEN_GROUPS NewState,
  DWORD BufferLength,
  PTOKEN_GROUPS PreviousState,
  PDWORD ReturnLength
)
                                                      
                         
{
}
-------------------------



And whamo-blamo, the documentation is generated...

Now, I'm not too hot on coding, did I just break
something to get my API to document? Should I be
adding a fixme? Should I be returning something even
though it's an empty function? I didn't compile it to
see if it worked.The AdjustTokenGroups.html file that
was generated says "Not defined in a Wine header. The
function is either undocumented, or missing from
Wine." Is it ok to leave that right now? Should I me
putting something in a header file somewhere?

Just wondering.

-Joshua