From 79e3a1be70dfd236d30ab2cb1dc837077e909b35 Mon Sep 17 00:00:00 2001
From: Markus Amsler <markus.amsler@oribi.org>
Date: Sat, 5 Nov 2005 10:45:02 +0000
Subject: [PATCH] Improve c2man Documented-Total count.

---
 dlls/gdi/driver.c      |  2 ++
 dlls/gdi/enhmetafile.c | 10 ++++++++++
 dlls/gdi/font.c        | 12 +++++++++++-
 dlls/gdi/metafile.c    | 19 +++++++++++++++++--
 dlls/gdi/mfdrv/init.c  |  2 ++
 dlls/gdi/painting.c    | 18 +++++++++++++-----
 dlls/gdi/palette.c     |  2 ++
 dlls/gdi/path.c        |  4 +++-
 8 files changed, 60 insertions(+), 9 deletions(-)

diff --git a/dlls/gdi/driver.c b/dlls/gdi/driver.c
index 269bbcaa6a1..29c1f47f459 100644
--- a/dlls/gdi/driver.c
+++ b/dlls/gdi/driver.c
@@ -661,6 +661,8 @@ INT WINAPI Escape( HDC hdc, INT escape, INT in_count, LPCSTR in_data, LPVOID out
 /******************************************************************************
  *		ExtEscape	[GDI32.@]
  *
+ * Access capabilities of a particular device that are not available through GDI.
+ *
  * PARAMS
  *    hdc         [I] Handle to device context
  *    nEscape     [I] Escape function
diff --git a/dlls/gdi/enhmetafile.c b/dlls/gdi/enhmetafile.c
index ed2a451bff7..c97e4cadd96 100644
--- a/dlls/gdi/enhmetafile.c
+++ b/dlls/gdi/enhmetafile.c
@@ -379,6 +379,10 @@ HENHMETAFILE WINAPI GetEnhMetaFileW(
 /*****************************************************************************
  *        GetEnhMetaFileHeader  (GDI32.@)
  *
+ * Retrieves the record containing the header for the specified
+ * enhanced-format metafile.
+ *
+ * RETURNS
  *  If buf is NULL, returns the size of buffer required.
  *  Otherwise, copy up to bufsize bytes of enhanced metafile header into
  *  buf.
@@ -404,6 +408,8 @@ UINT WINAPI GetEnhMetaFileHeader(
 
 /*****************************************************************************
  *          GetEnhMetaFileDescriptionA  (GDI32.@)
+ *
+ * See GetEnhMetaFileDescriptionW.
  */
 UINT WINAPI GetEnhMetaFileDescriptionA(
        HENHMETAFILE hmf, /* [in] enhanced metafile */
@@ -433,6 +439,7 @@ UINT WINAPI GetEnhMetaFileDescriptionA(
  *  Copies the description string of an enhanced metafile into a buffer
  *  _buf_.
  *
+ * RETURNS
  *  If _buf_ is NULL, returns size of _buf_ required. Otherwise, returns
  *  number of characters copied.
  */
@@ -2369,6 +2376,9 @@ static INT CALLBACK EMF_PlayEnhMetaFileCallback(HDC hdc, HANDLETABLE *ht,
  *    Renders an enhanced metafile into a specified rectangle *lpRect
  *    in device context hdc.
  *
+ * RETURNS
+ *    Success: TRUE
+ *    Failure: FALSE
  */
 BOOL WINAPI PlayEnhMetaFile(
        HDC hdc,           /* [in] DC to render into */
diff --git a/dlls/gdi/font.c b/dlls/gdi/font.c
index 4de95f3ca8c..301a17ecd42 100644
--- a/dlls/gdi/font.c
+++ b/dlls/gdi/font.c
@@ -1060,6 +1060,8 @@ INT WINAPI GetTextFaceW( HDC hdc, INT count, LPWSTR name )
 
 /***********************************************************************
  *           GetTextExtentPoint32A    (GDI32.@)
+ *
+ * See GetTextExtentPoint32W.
  */
 BOOL WINAPI GetTextExtentPoint32A( HDC hdc, LPCSTR str, INT count,
                                      LPSIZE size )
@@ -2183,7 +2185,7 @@ BOOL WINAPI TextOutW(HDC hdc, INT x, INT y, LPCWSTR str, INT count)
 /***********************************************************************
  *		PolyTextOutA (GDI32.@)
  *
- * Draw several Strings
+ * See PolyTextOutW.
  */
 BOOL WINAPI PolyTextOutA ( HDC hdc,               /* [in] Handle to device context */
                            PPOLYTEXTA pptxt,      /* [in] Array of strings */
@@ -2201,6 +2203,10 @@ BOOL WINAPI PolyTextOutA ( HDC hdc,               /* [in] Handle to device conte
  *		PolyTextOutW (GDI32.@)
  *
  * Draw several Strings
+ *
+ * RETURNS
+ *  TRUE:  Success.
+ *  FALSE: Failure.
  */
 BOOL WINAPI PolyTextOutW ( HDC hdc,               /* [in] Handle to device context */
                            PPOLYTEXTW pptxt,      /* [in] Array of strings */
@@ -2256,6 +2262,8 @@ BOOL WINAPI GetAspectRatioFilterEx( HDC hdc, LPSIZE pAspectRatio )
 
 /***********************************************************************
  *           GetCharABCWidthsA   (GDI32.@)
+ *
+ * See GetCharABCWidthsW.
  */
 BOOL WINAPI GetCharABCWidthsA(HDC hdc, UINT firstChar, UINT lastChar,
                                   LPABC abc )
@@ -2624,6 +2632,8 @@ DWORD WINAPI GetGlyphIndicesW(HDC hdc, LPCWSTR lpstr, INT count,
 /*************************************************************************
  * GetCharacterPlacementA [GDI32.@]
  *
+ * See GetCharacterPlacementW.
+ *
  * NOTES:
  *  the web browser control of ie4 calls this with dwFlags=0
  */
diff --git a/dlls/gdi/metafile.c b/dlls/gdi/metafile.c
index 1423c7dd6ad..12198882ad1 100644
--- a/dlls/gdi/metafile.c
+++ b/dlls/gdi/metafile.c
@@ -483,6 +483,8 @@ HMETAFILE WINAPI CopyMetaFileW( HMETAFILE hSrcMetaFile, LPCWSTR lpFilename )
 
 /******************************************************************
  *         CopyMetaFileA   (GDI32.@)
+ *
+ * See CopyMetaFileW.
  */
 HMETAFILE WINAPI CopyMetaFileA( HMETAFILE hSrcMetaFile, LPCSTR lpFilename )
 {
@@ -618,6 +620,10 @@ BOOL16 WINAPI PlayMetaFile16( HDC16 hdc, HMETAFILE16 hmf )
  * PARAMS
  *  hdc [I] handle of DC to render in
  *  hmf [I] handle of metafile to render
+ *
+ * RETURNS
+ *  Success: TRUE
+ *  Failure: FALSE
  */
 BOOL WINAPI PlayMetaFile( HDC hdc, HMETAFILE hmf )
 {
@@ -1323,6 +1329,9 @@ HGLOBAL16 WINAPI GetMetaFileBits16( HMETAFILE16 hmf )
  *
  * PARAMS
  *  hMem [I] handle to a memory region holding a metafile
+ *
+ * RETURNS
+ *  Handle to a metafile on success, NULL on failure..
  */
 HMETAFILE16 WINAPI SetMetaFileBits16( HGLOBAL16 hMem )
 {
@@ -1358,6 +1367,10 @@ HMETAFILE16 WINAPI SetMetaFileBitsBetter16( HMETAFILE16 hMeta )
  * PARAMS
  *  size   [I] size of metafile, in bytes
  *  lpData [I] pointer to metafile data
+ *
+ * RETURNS
+ *  Success: Handle to metafile.
+ *  Failure: NULL.
  */
 HMETAFILE WINAPI SetMetaFileBitsEx( UINT size, const BYTE *lpData )
 {
@@ -1390,13 +1403,15 @@ HMETAFILE WINAPI SetMetaFileBitsEx( UINT size, const BYTE *lpData )
  * Get raw metafile data.
  *
  *  Copies the data from metafile _hmf_ into the buffer _buf_.
- *  If _buf_ is zero, returns size of buffer required. Otherwise,
- *  returns number of bytes copied.
  *
  * PARAMS
  *  hmf   [I] metafile
  *  nSize [I] size of buf
  *  buf   [O] buffer to receive raw metafile data
+ *
+ * RETURNS
+ *  If _buf_ is zero, returns size of buffer required. Otherwise,
+ *  returns number of bytes copied.
  */
 UINT WINAPI GetMetaFileBitsEx( HMETAFILE hmf, UINT nSize, LPVOID buf )
 {
diff --git a/dlls/gdi/mfdrv/init.c b/dlls/gdi/mfdrv/init.c
index dfeafcf53ec..02cf7772d4f 100644
--- a/dlls/gdi/mfdrv/init.c
+++ b/dlls/gdi/mfdrv/init.c
@@ -275,6 +275,8 @@ HDC WINAPI CreateMetaFileW( LPCWSTR filename )
 
 /**********************************************************************
  *          CreateMetaFileA   (GDI32.@)
+ *
+ * See CreateMetaFileW.
  */
 HDC WINAPI CreateMetaFileA(LPCSTR filename)
 {
diff --git a/dlls/gdi/painting.c b/dlls/gdi/painting.c
index 61643c1945a..62f7f47b43f 100644
--- a/dlls/gdi/painting.c
+++ b/dlls/gdi/painting.c
@@ -340,7 +340,9 @@ INT WINAPI ChoosePixelFormat( HDC hdc, const PIXELFORMATDESCRIPTOR* ppfd )
  *    iPixelFormat [I] Pixel format index
  *    ppfd         [I] Pixel format for which a match is sought
  *
- * RETURNS STD
+ * RETURNS
+ *    Success: TRUE
+ *    Failure: FALSE
  */
 BOOL WINAPI SetPixelFormat( HDC hdc, INT iPixelFormat,
                             const PIXELFORMATDESCRIPTOR *ppfd)
@@ -433,7 +435,9 @@ INT WINAPI DescribePixelFormat( HDC hdc, INT iPixelFormat, UINT nBytes,
  * PARAMS
  *    hdc [I] Device context whose buffers get swapped
  *
- * RETURNS STD
+ * RETURNS
+ *    Success: TRUE
+ *    Failure: FALSE
  */
 BOOL WINAPI SwapBuffers( HDC hdc )
 {
@@ -689,7 +693,9 @@ BOOL WINAPI FloodFill( HDC hdc, INT x, INT y, COLORREF color )
  *    lppt    [I] Pointer to endpoints and control points
  *    cPoints [I] Count of endpoints and control points
  *
- * RETURNS STD
+ * RETURNS
+ *    Success: TRUE
+ *    Failure: FALSE
  */
 BOOL WINAPI PolyBezier( HDC hdc, const POINT* lppt, DWORD cPoints )
 {
@@ -732,7 +738,9 @@ BOOL WINAPI PolyBezier( HDC hdc, const POINT* lppt, DWORD cPoints )
  *    lppt    [I] Pointer to endpoints and control points
  *    cPoints [I] Count of endpoints and control points
  *
- * RETURNS STD
+ * RETURNS
+ *    Success: TRUE
+ *    Failure: FALSE
  */
 BOOL WINAPI PolyBezierTo( HDC hdc, const POINT* lppt, DWORD cPoints )
 {
@@ -1134,7 +1142,7 @@ POINT *GDI_Bezier( const POINT *Points, INT count, INT *nPtsOut )
 }
 
 /******************************************************************************
- *           GradientFill   (GDI32.@)
+ *           GdiGradientFill   (GDI32.@)
  *
  *  FIXME: we don't support the Alpha channel properly
  */
diff --git a/dlls/gdi/palette.c b/dlls/gdi/palette.c
index 80ae49585f2..37cce31ab17 100644
--- a/dlls/gdi/palette.c
+++ b/dlls/gdi/palette.c
@@ -491,6 +491,8 @@ BOOL WINAPI AnimatePalette(
 /***********************************************************************
  * SetSystemPaletteUse [GDI32.@]
  *
+ * Specify whether the system palette contains 2 or 20 static colors.
+ *
  * RETURNS
  *    Success: Previous system palette
  *    Failure: SYSPAL_ERROR
diff --git a/dlls/gdi/path.c b/dlls/gdi/path.c
index 7137f7b6c2d..216c7d05765 100644
--- a/dlls/gdi/path.c
+++ b/dlls/gdi/path.c
@@ -201,7 +201,9 @@ BOOL WINAPI EndPath(HDC hdc)
  * PARAMS
  *    hdc [I] Handle to device context
  *
- * RETURNS STD
+ * RETURNS
+ *    Success: TRUE
+ *    Failure: FALSE
  */
 BOOL WINAPI AbortPath( HDC hdc )
 {