代码注释与文档生成工具: epydoc与doxygen

/*! A test class */class Test{  public:    /** An enum type.      *  The documentation block cannot be put after the enum!      */    enum EnumType    {      int EVal1,     /**< enum value 1 */      int EVal2      /**< enum value 2 */    };    void member();   //!< a member function.  protected:    int value;       /*!< an integer value */};/////////////////////////////////////////////////////////** *  A test class. A more elaborate class description. */class Test{  public:    /**      * An enum.     * More detailed enum description.     */    enum TEnum {           TVal1, /**< enum value TVal1. */            TVal2, /**< enum value TVal2. */            TVal3  /**< enum value TVal3. */           }        *enumPtr, /**< enum pointer. Details. */       enumVar;  /**< enum variable. Details. */      /**       * A constructor.       * A more elaborate description of the constructor.       */      Test();      /**       * A destructor.       * A more elaborate description of the destructor.       */     ~Test();      /**       * a normal member taking two arguments and returning an integer value.       * @param a an integer argument.       * @param s a constant character pointer.       * @see Test()       * @see ~Test()       * @see testMeToo()       * @see publicVar()       * @return The test results       */       int testMe(int a,const char *s);      /**       * A pure virtual member.       * @see testMe()       * @param c1 the first argument.       * @param c2 the second argument.       */       virtual void testMeToo(char c1,char c2) = 0;      /**        * a public variable.       * Details.       */       int publicVar;      /**       * a function variable.       * Details.       */       int (*handler)(int a,int b);};

3.6 常用标签命令

标签 说明 @author作者@brief摘要@file文件说明 @version版本@todo改进内容 @var模块变量说明@typedef模块变量类型说明 @param参数说明@arg列表说明参数@return返回值@retval返回值类型 @note注解@attention注意@bug存在的问题@warning警告 @see参考信息

3.7 特殊标记命令

doxygen的文档很详细，支持的标记命令也很多: http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdparam

4 后记

听了很多道理，依旧过不好这一生；学了很多文档标记，依旧写不好文档。

5 参考

http://en.wikipedia.org/wiki/Doxygenhttp://www.stack.nl/~dimitri/doxygen/index.htmlhttp://stackoverflow.com/questions/4126421/how-to-document-python-code-epydoc-doxygen-sphinxhttp://sphinx-doc.org/https://pypi.python.org/pypi/epydochttp://www.ast.cam.ac.uk/~rgm/dazle/software/dics/src/epydoc-3.0alpha2/doc/index.html

▲

---

作者简介：

朱春来(Leslie Zhu)，金融工程师，毕业于西安电子科技大学, 喜欢历史，喜欢编程. 日常在GNU/Linux环境下进行C/C++、Python开发，对Common Lisp、Node.js、金融等感兴趣。可以通过邮箱(pythonisland@gmail.com)联系他，或者直接在他的个人主页上留言.

访问朱春来(Leslie Zhu)的个人主页(http://lesliezhu.github.com)

原文地址：代码注释与文档生成工具: epydoc与doxygen, 感谢原作者分享。 初初尝试着拥抱的人，一派新鲜幸福都来不及沉浸，