c2man comment rejection

[Markus Amsler]

Hi,

I identified 80 function comments, that have a description and a PARAMS 
section, but no RETURNS section. IMHO it would generate in most cases 
acceptable documentation, but gets rejected because of the missing 
RETURNS section.

2 possible fixes:
 - patch c2man so it accepts also PARAMS sections
   pro: small change, more html documented functions in general
   con: some functions have unsuitable comments
 - add RETURNS section to comments
   pro: cleaner documentation
   con: more changes, a lot of "RETURNS TRUE on success FALSE 
otherwise"- style comments.

Which way to go?

Markus


identified Functions:

IsTextUnicode
CryptAcquireContextW
SystemFunction036
SystemFunction040
SystemFunction041
BuildSecurityDescriptorA
SetFileSecurityW
StartServiceCtrlDispatcherA
StartServiceCtrlDispatcherW
GetEnhMetaFileHeader
GetEnhMetaFileDescriptionW
PlayEnhMetaFile
PolyTextOutA
PolyTextOutW
GdiInit216
PlayMetaFile
GetMetaFileBits16
SetMetaFileBits16
SetMetaFileBitsEx
GetMetaFileBitsEx
SetPixelFormat
SwapBuffers
PolyBezier
PolyBezierTo
AbortPath
WaitCommEvent
CommConfigDialogW
WriteConsoleOutputCharacterA
SetConsoleCursorPosition
GetDriveType16
IsValidLocale
SetLastError
GetLastError
GetCurrentProcessId
GetCurrentThreadId
SetLastError
ThunkConnect32
ThunkInitSL
SSCall
FreeSLCallback
ThunkConnect16
VirtualAllocEx
GetColorDirectoryW
ICInfo
AcceptEx
TransmitFile
RtlSetLastWin32Error
RtlSetLastWin32ErrorAndNtStatusFromNtStatus
RtlOpenCurrentUser
RtlCreateSecurityDescriptor
RtlCopySecurityDescriptor
_splitpath
CreateILockBytesOnHGlobal16
CoInitialize16
ProgIDFromCLSID16
CoRegisterClassObject16
ReadClassStg16
SetupOpenInfFileW
ILAppend
ILFree
ILGlobalFree
RegisterShellHook
SHUpdateImageW
IShellFolder_ParseDisplayName
SHFileOperationA
SHFreeNameMappings
IUnknown_SetSite
CreateIcon
SetCursor
SetDebugErrorLevel
DestroyAcceleratorTable
SetScrollRange
ShowScrollBar
OpenThemeFile
CloseThemeFile
ApplyTheme
GetThemeDefaults
EnumThemes
CheckThemeSignature
EnumPrintersW