documentation/documentation.sgml

   1   <chapter id="documentation">
   2     <title>Documenting Wine</title>
   3     <para>How to help out with the Wine documentation effort...</para>
   4
   5     <sect1 id="api-docs">
   6       <title>Writing Wine API Documentation</title>
   7
   8       <para>
   9         written by (???)
  10       </para>
  11       <para>
  12         (Extracted from <filename>wine/documentation/README.documentation</filename>)
  13       </para>
  14
  15       <para>
  16         To improve the documentation of the Wine API, just add
  17         comments to the existing source. For example,
  18       </para>
  19       <screen>
  20 /******************************************************************
  21  *         CopyMetaFile32A   (GDI32.23)
  22  *
  23  *  Copies the metafile corresponding to hSrcMetaFile to either
  24  *  a disk file, if a filename is given, or to a new memory based
  25  *  metafile, if lpFileName is NULL.
  26  *
  27  * RETURNS
  28  *
  29  *  Handle to metafile copy on success, NULL on failure.
  30  *
  31  * BUGS
  32  *
  33  *  Copying to disk returns NULL even if successful.
  34  */
  35 HMETAFILE32 WINAPI CopyMetaFile32A(
  36                    HMETAFILE32 hSrcMetaFile, /* handle of metafile to copy */
  37                    LPCSTR lpFilename /* filename if copying to a file */
  38 ) { ... }
  39       </screen>
  40       <para>
  41         becomes, after processing with <command>c2man</command> and
  42         <command>nroff -man</command>,
  43       </para>
  44       <screen>
  45 CopyMetaFileA(3w)                               CopyMetaFileA(3w)
  46
  47
  48 NAME
  49        CopyMetaFileA - CopyMetaFile32A   (GDI32.23)
  50
  51 SYNOPSIS
  52        HMETAFILE32 CopyMetaFileA
  53        (
  54             HMETAFILE32 hSrcMetaFile,
  55             LPCSTR lpFilename
  56        );
  57
  58 PARAMETERS
  59        HMETAFILE32 hSrcMetaFile
  60               Handle of metafile to copy.
  61
  62        LPCSTR lpFilename
  63               Filename if copying to a file.
  64
  65 DESCRIPTION
  66        Copies  the  metafile  corresponding  to  hSrcMetaFile  to
  67        either a disk file, if a filename is given, or  to  a  new
  68        memory based metafile, if lpFileName is NULL.
  69
  70 RETURNS
  71        Handle to metafile copy on success, NULL on failure.
  72
  73 BUGS
  74        Copying to disk returns NULL even if successful.
  75
  76 SEE ALSO
  77        GetMetaFileA(3w),   GetMetaFileW(3w),   CopyMetaFileW(3w),
  78        PlayMetaFile(3w),  SetMetaFileBitsEx(3w),  GetMetaFileBit-
  79        sEx(3w)
  80       </screen>
  81     </sect1>
  82   </chapter>
  83
  84 <!-- Keep this comment at the end of the file
  85 Local variables:
  86 mode: sgml
  87 sgml-parent-document:("wine-doc.sgml" "book" "part" "chapter" "")
  88 End:
  89 -->