3

In c# you can have descriptions like this:

    /// <summary>
    /// Return true if channel contains the given user name
    /// </summary>
    /// <param name="user"></param>
    /// <returns></returns>
    public bool ContainsUser(string user)
    { ...

Is anything like that standardised or widely used in c++? Are some IDE's able to parse this kind of information just like Visual Studio does it in c# and display some hints thanks to that?

Petr
  • 13,747
  • 20
  • 89
  • 144
  • 6
    see doxygen comments – qwr Jun 23 '13 at 11:36
  • 3
    Related: [Is Doxygen the de-facto standard documentation syntax specification](http://stackoverflow.com/questions/3581450/is-doxygen-the-de-facto-standard-documentation-syntax-specification), which was asked in a C++ context. – jogojapan Jun 23 '13 at 11:38
  • doxygen. I haven't seen IDEs make much use of it inside the editor. – Frank Osterfeld Jun 23 '13 at 11:41
  • 2
    For VS you can use same doc syntax as c# and use /doc switch: http://msdn.microsoft.com/en-us/library/ms173501.aspx – zahir Jun 23 '13 at 11:52
  • ok can these doxygen be in .h or .cpp files? – Petr Jun 23 '13 at 12:59
  • note: if you have proper method names, that's just *noise*. What you posted is the epitome of why you don't need it. Does it give you *any* extra information? Zero. These comments make sense for public facing API-s, or some complex methods, but for the rest (95%), it's pointless to create it. – Karoly Horvath Aug 17 '13 at 17:56

2 Answers2

3

Check out Coding Style and Doxygen Documentation. Particularly, you want to see the following sections:

  • Comments for Files
  • Comments for Functions and Data Structures
  • Coding Style / Coding Standards
  • Description of Commands
herohuyongtao
  • 49,413
  • 29
  • 133
  • 174
0

Like Karoly says, it's just noise. In scripting languages, the noise is appreciated because scripts are often minified and use tricks that are often unintuitive to the reader. In Visual Studio, it seems to be a Microsoft "trademark" to have functions that are self-documentating. It helps Intellisense mostly. Personally, I think it's quite irritating to scroll through code and read 90% comments, and 10% code. You'll notice that Doxygen created documents tend to be completely useless. Because of their self-documenting nature, at most, you'll get a generated list of class names, function names, and an "API", but it is only helpful as a reference.

Keep the Doxygen document (if you wish) as a reference, but provide actual documentation by commenting your code in a practical manner, keeping the signal-to-noise ratio low, and doing hand documentation.