After spending some hours trying to get intelisense to work, I've failed, the only way of making it work is using XML style documentation, that uses something similar to:
/// This functions documentation
/// <param name="aa">blablabla</param>
bool function1(TypeX aa);
Looks like this style it's also accepted by Doxygen, and it's automatically processed and shown by Visual Studio Intellisense.
I see it one advantage over:
And that's that you can comment entire sections of code, because you won't have a '*/' in the middle of the code.
Anyway I don't personally like it, I'd suggest:
* Use doxygen as the generator of the documentation
* Make header (.h) documentation mandatory
* Make code (.cc) documentation optional, only if extends the meaning
* \param a explanation
* \param b explanation
* \return explanation
That information must be mandatory, any new method *HAS* to be docuemnted, and one can't touch a function already in code and leave it undocumented.
And for ocasional extra explanations in-code, use ///
I'd stick the documentations in the .h because it looks more natural to me, but said this, I don't mind if we agree in documentating just the .cc. But I'd like to reach one decision and see all the code documented the same way.