linux tutorial c++ coding style, standards and practices.mht

linux下c++编程的好文章

      <TABLE cellSpacing=3D0 cellPadding=3D2 width=3D"100%" border=3D0>
        <TBODY>
        <TR bgColor=3D#ffcc33>
          <TD><B><BIG>C++ Automated Documentation=20
        Generation:</BIG></B></TD></TR></TBODY></TABLE>
      <P>
      <UL>
        <LI><B>ScanDoc:</B> Perl script which scans C++ source code for=20
        specially-formatted comments and produces organized, indexed=20
        documentation. <BR><A =
href=3D"http://scandoc.sourceforge.net/">scandoc=20
        home page</A>=20
        <P></P>
        <LI><B>HeaderBrowser:</B> Create documents from file headers =
<BR><A=20
        href=3D"http://www.headerbrowser.org/">HeaderBrowser home =
page</A>=20
      </LI></UL><A name=3DDOXYGEN></A>
      <P>
      <HR noShade SIZE=3D5>

      <TABLE cellSpacing=3D0 cellPadding=3D2 width=3D"100%" border=3D0>
        <TBODY>
        <TR bgColor=3D#c0c0c0>
          <TD><B><BIG>dOxygen and C++ Automated Documentation=20
            Generation:</BIG></B></TD></TR></TBODY></TABLE>
      <P>
      <P><B>dOxygen:</B> cross-platform, JavaDoc-like documentation =
system for=20
      C++, Java, C, and IDL. DOxygen is included with the base release =
of most=20
      Linux distributions including Red Hat and SuSE. DOxygen tags =
support two=20
      basic format styles, \<I>tagname</I> or @<I>tagname</I>. The later =
is the=20
      Javadoc style which is shown in this tutorial.=20
      <P><A =
href=3D"http://www.stack.nl/~dimitri/doxygen/index.html">Doxygen home=20
      page</A> - <A=20
      =
href=3D"http://freshmeat.net/projects/doxygen/?topic_id=3D847%2C45">doxyg=
en=20
      freshmeat page</A>=20
      <P><B>Example:</B>=20
      <DL>
        <DD>
        <TABLE cellSpacing=3D1 cellPadding=3D4 width=3D"100%" =
bgColor=3D#000000=20
border=3D1>
          <TBODY>
          <TR bgColor=3D#c0c0c0>
            <TD><PRE>// $Id$
/**
 * @file
 * @brief Write description of source file here for dOxygen.
 * @brief Must use "brief" tag to generate comments for file =
documentation.
 * @author Me
 * @version 1.69
 */
// $Log$
=20
///  Single line comment for dOxygen.
=20
/**
   Write description of function here.
   The function should follow these comments.
   Use of "brief" tag is optional. (no point to it)
 =20
   The function arguments listed with "param" will be compared=20
   to the declaration and verified.

   @param <I>argOne</I> Description of first function argument.
   @param <I>argTwo</I> Description of second function argument.
   @return Description of returned value.
 */
=20
int
class::function(arg1, arg2)
{
=20
    /// Single line comment for dOxygen.
}
    </PRE></TD></TR></TBODY></TABLE>Note the tags "$Id$" and "$Log$" are =

        used by RCS. </DD></DL>
      <P>Headings generated from tags:=20
      <DL>
        <DD>
        <TABLE border=3D1>
          <TBODY>
          <TR bgColor=3D#c0c0c0>
            <TH>dOxygen tag</TH>
            <TH>Rendering</TH></TR>
          <TR>
            <TD>@file <I>file-name</I></TD>
            <TD>Prints <I>file-name</I> as header of page.</TD></TR>
          <TR>
            <TD>@brief <I>Brief description goes here.</I></TD>
            <TD>Description appears in HTML document =
generated.</TD></TR>
          <TR>
            <TD>@author <I>name1</I><BR>@author <I>name2</I></TD>
            <TD><B>Author:</B>
              <DL>
                =
<DD><I><TT>name1</TT></I><BR><I><TT>name2</TT></I></DD></DL></TD></TR>
          <TR>
            <TD>@version <I>Version number</I></TD>
            <TD><B>Version:</B>
              <DL>
                <DD><I><TT>Version number()</TT></I></DD></DL></TD></TR>
          <TR>
            <TD>@depricated <I>explanation</I></TD>
            <TD><B>Depricated:</B>
              <DL>
                <DD><I><TT>explanation</TT></I></DD></DL></TD></TR>
          <TR>
            <TD>@see <I>FunctionA()</I></TD>
            <TD><B>See also:</B>
              <DL>
                <DD><I><TT>FunctionA()</TT></I></DD></DL></TD></TR>
          <TR>
            <TD>@param[in] <I>variableA DescriptionA</I><BR>@param[out]=20
              <I>variableB DescriptionB</I><BR>@param[in,out] =
<I>variableC=20
              DescriptionC</I><BR>Note: <TT>in</TT> and <TT>out</TT> are =
dOxygen=20
              specific and not used in Javadoc.</TD>
            <TD><B>Parameters:</B>
              <DL>
                <DD><I><TT>variableA DescriptionA<BR>variableB=20
                DescriptionB<BR>variableC =
DescriptionC</TT></I></DD></DL></TD></TR>
          <TR>
            <TD>@return <I>variableA</I></TD>
            <TD><B>Returns:</B>
              <DL>
                <DD><I><TT>variableA</TT></I></DD></DL></TD></TR>
          <TR>
            <TD>@bug <I>Description of bug goes here</I></TD>
            <TD><B>Bug:</B>
              <DL>
                <DD><I><TT>Description of bug goes =
here</TT></I></DD></DL></TD></TR>
          <TR>
            <TD>@warning <I>Warning message goes here</I></TD>
            <TD><B>Warning:</B>
              <DL>
                <DD><I><TT>Warning message goes=20
          here</TT></I></DD></DL></TD></TR></TBODY></TABLE></DD></DL>
      <P>Full list of dOxygen Tags: <A=20
      =
href=3D"http://www.stack.nl/~dimitri/doxygen/commands.html">http://www.st=
ack.nl/~dimitri/doxygen/commands.html</A>=20
      <BR>Javadoc tags: <A=20
      =
href=3D"http://java.sun.com/j2se/javadoc/writingdoccomments/">http://java=
.sun.com/j2se/javadoc/writingdoccomments/</A>=20
      <BR>Note the difference between the dOxygen @throw and the Javadoc =
@throws=20
      tag.=20
      <P>dOxygen tags for <TT>@brief</TT> are not necessary if using=20
      <TT>JAVADOC_AUTOBRIEF</TT> (yes) mode. this will print the first =
line in a=20
      "/**" comment block as the brief description.=20
      <P>The tagged dOxygen comments are placed ahead of the C++ =
function, class=20
      or variable. Comments placed after a C++ entity can be tagged with =

      "<TT>/**&lt; ... */</TT>".=20
      <DL>
        <DD>
        <TABLE cellSpacing=3D1 cellPadding=3D4 width=3D"100%" =
bgColor=3D#000000=20
border=3D1>
          <TBODY>
          <TR bgColor=3D#c0c0c0>
            <TD><PRE>/** Comments on C++ function
 ...
 ...
 */

void classA::function_1( int   <I>variable1</I>, /**&lt; <I>Comment on =
variable goes here.</I> */
                         float <I>variable2</I>, /**&lt; <I>Comment on =
variable goes here.</I> */
                         ...                   ,
                         ... )
{
   ...
</PRE></TD></TR></TBODY></TABLE>Note: It is only usefull to apply this=20
        to an include file (.h, .hpp) or functions in a ".cpp" or ".C" =
file, but=20
        not both. If attributed in both, then the "Attributes" section =
and=20
        comments will appear in the documentation twice. </DD></DL>
      <P>Create a list:=20
      <DL>
        <DD>
        <TABLE cellSpacing=3D1 cellPadding=3D4 width=3D"100%" =
bgColor=3D#000000=20
border=3D1>
          <TBODY>
          <TR bgColor=3D#c0c0c0>
            <TD><PRE>/**  List heading:
     - Stuff on line 1
     - Stuff on line 2
     - Stuff on line 3
       - Stuff on sub-line 1
       - Stuff on sub-line 2
     - Stuff on line 4
 */
</PRE></TD></TR></TBODY></TABLE></DD></DL>This creates a bulletized list =

      in HTML. To generate a numbered list use "-#". One may also use =
HTML=20
      directly in the comment block. See <A=20
      =
href=3D"http://www.stack.nl/~dimitri/doxygen/htmlcmds.html">http://www.st=
ack.nl/~dimitri/doxygen/htmlcmds.html</A>=20

      <P>Pages of documentation are defined by a group. You can specify =
the=20
      group directly using the tags:=20
      <UL>
        <LI>@defgroup=20
        <LI>@ingroup </LI></UL>
      <P>The group is delimited by:=20
      <DL>
        <DD>
        <TABLE cellSpacing=3D1 cellPadding=3D4 width=3D"100%" =
bgColor=3D#000000=20
border=3D1>
          <TBODY>
          <TR bgColor=3D#c0c0c0>
            <TD><PRE>//@{
...
...
//@}
</PRE></TD></TR></TBODY></TABLE></DD></DL>
      <P><B>Configuration file:</B> <TT><I>project-name</I>.cfg</TT> =
<BR>Create=20
      template configuration file and tag descriptions with the command: =

      <TT>doxygen -g <I>project-name</I>.cfg</TT>=20
      <DL>
        <DD>
        <TABLE cellSpacing=3D1 cellPadding=3D4 width=3D"100%" =
bgColor=3D#000000=20
border=3D1>
          <TBODY>
          <TR bgColor=3D#c0c0c0>
            <TD><SMALL><PRE># Doxyfile 1.4.4

# This file describes the settings to be used by the documentation =
system
# doxygen (www.doxygen.org) for a project
#
# All text after a hash (#) is considered a comment and will be ignored
# The format is:
#       TAG =3D value [value, ...]
# For lists items can also be appended using:
#       TAG +=3D value [value, ...]
# Values that contain spaces should be placed between quotes (" ")

#------------------------------------------------------------------------=
---
# Project related configuration options
#------------------------------------------------------------------------=
---

PROJECT_NAME      =3D "<I>Project XXX</I>"
PROJECT_NUMBER         =3D=20
OUTPUT_DIRECTORY  =3D <I>project</I>
CREATE_SUBDIRS         =3D NO
OUTPUT_LANGUAGE        =3D English
USE_WINDOWS_ENCODING   =3D NO

# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will=20
# include brief member descriptions after the members that are listed in =

# the file and class documentation (similar to JavaDoc).=20
# Set to NO to disable this.

BRIEF_MEMBER_DESC      =3D YES

# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will =
prepend=20
# the brief description of a member or function before the detailed =
description.=20
# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, =
the=20
# brief descriptions will be completely suppressed.

REPEAT_BRIEF           =3D YES

# This tag implements a quasi-intelligent brief description abbreviator=20
# that is used to form the text in various listings. Each string=20
# in this list, if found as the leading text of the brief description, =
will be=20
# stripped from the text and the result after processing the whole list, =
is=20
# used as the annotated text. Otherwise, the brief description is used =
as-is.=20
# If left blank, the following values are used ("$name" is automatically =

# replaced with the name of the entity): "The $name class" "The $name =
widget"=20
# "The $name file" "is" "provides" "specifies" "contains"=20
# "represents" "a" "an" "the"

ABBREVIATE_BRIEF       =3D=20

# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES =
then=20
# Doxygen will generate a detailed section even if there is only a brief =

# description.

ALWAYS_DETAILED_SEC    =3D NO

# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all=20
# inherited members of a class in the documentation of that class as if =
those=20
# members were ordinary class members. Constructors, destructors and =
assignment=20
# operators of the base classes will not be shown.

INLINE_INHERITED_MEMB  =3D NO

# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the =
full=20
# path before files name in the file list and in the header files. If =
set=20
# to NO the shortest path that makes the file name unique will be used.

<B>FULL_PATH_NAMES        =3D NO</B>

# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag=20
# can be used to strip a user-defined part of the path. Stripping is=20
# only done if one of the specified strings matches the left-hand part =
of=20
# the path. The tag can be used to show relative paths in the file list. =

# If left blank the directory from which doxygen is run is used as the=20
# path to strip.

STRIP_FROM_PATH        =3D=20

# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part =
of=20
# the path mentioned in the documentation of a class, which tells=20
# the reader which header file to include in order to use a class.=20
# If left blank only the name of the header file containing the class=20
# definition is used. Otherwise one should specify the include paths =
that=20
# are normally passed to the compiler using the -I flag.

STRIP_FROM_INC_PATH    =3D=20

# If the SHORT_NAMES tag is set to YES, doxygen will generate much =
shorter=20
# (but less readable) file names. This can be useful is your file =
systems=20
# doesn't support long names like on DOS, Mac, or CD-ROM.

SHORT_NAMES            =3D NO

# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen=20
# will interpret the first line (until the first dot) of a JavaDoc-style =

# comment as the brief description. If set to NO, the JavaDoc=20
# comments will behave just like the Qt-style comments (thus requiring =
an=20