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
On 11/3/05, Markus Amsler <markus.amsler(a)oribi.org> wrote:
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?
My personal choice would be to add the RETURNS TRUE/FALSE where needed to be consistent with the rest of the comments. It will be cleaner, and a few no-op changes isn't so bad of a con. -- James Hawkins
participants (3)
-
Dimi Paun -
James Hawkins -
Markus Amsler