1.1.1.2 Comment and document

• Only use comment when it’s very necessary.
• Use C++ and doxygen style comment more, use C style comment less.
  /// \brief fooFun does ... 
  /// 
  ///if \p flag is true, when happen 
  ///\param [out] result will be filled 
  ///\return 0 on success. 
  bool fooFun(bool flag, int& result);
• When you want to comment a large block of code out, use #if 0 ... #endif, It’s better than using /* ... */
• Don’t duplicate the function or class name in comment. Maybe you will change name later, this inconsistent will confuse future comment reader.
• Install doxygen in linux, then run doxygen -g to produce configure file Doxyfile. In Doxyfile
  GENERATE_LATEX = NO  
  INPUT = ./src

  then run $ doxygen Doxyfile &x#21B2;, A html directory will be built.

• Usually you have a standard tree structure of project, that is to say every .cpp has .h file. Under this circumstance, you should put comment command in .h file. Because .h file is an interface to customer.
• If a .cpp file include a .h file, doxygen will not parse the .cpp file automatically, It only parse all .h file in certain directory.
• In order to make doxygen to parse a .cpp file , you need to put Doxygen command\file in a separate line in the .cpp file, then doxygen will parse this .cpp file and produce the corresponding html page.
• Given a C++ source code section, Doxygen will product below html page. References and Referenced can be turn on in the configure files.
  /// \brief Return the function this instruction belongs to. 
  /// 
  /// Note: it is undefined behavior to call this on an 
  /// instruction not currently inserted into a function. 
  const Function *getFunction() const;