I'll register my mild opposition to this here. It seems if we are going through the work to document internal methods and member variables then we might as well follow the Doxygen style. This is largely an academic point for member variables but for methods doxygen provides a structured way of documenting arguments and return semantics that is just as relevant for private methods. The default Doxygen config can be set up to ignore private docs, but for someone new to the code base being able to run Doxygen with the call graph feature and all private documentation enabled seems a good way to create browsable overview documentation (I've used this in past projects, but admittedly we had more extensive documentation of private data and methods from the beginning).

I don't have a strong opinion here. I guess I would say that in a perfect world, all methods, etc. would have doxygen comments. Realistically though, it's hard enough to get people doing it for public methods and class comments, and I think in most cases people will just not comment on private methods/members instead of going through the whole doxygen dance. So, giving into the reality of human nature I would tend to agree with @htuch. But happy to get some more opinions.

I don't necessarily think it should be mandatory to have doxygen comments for internal members/methods, just that if you're going to write such a comment it shouldn't be deliberately formatted to be ignored by Doxygen.

It does increase the activation energy to comment by forcing people to document every arg/return. I might want to add a quick:

// foo does bar
int foo(char arg);

comment, I don't necessarily want to add full docs for return/args, but the documentation is better than nothing.

agreed

I think I'd still prefer that we just relax the requirement for "going full doxygen" for private docs rather than mandating that private member/method have comments that Doxygen must ignore. Even in your example "foo does bar" is a perfectly reasonable comment for Doxygen to pick up as an internal method, extensive return type documentation isn't mandatory. In other words: Suggest but not require that private members/methods have a doxygen style comment, and make no hard mandates about all doxygen metadata being populated.

But, I like documenting things pretty extensively as part of my mental code writing process so that's my bias...

Yeah I can't say that I really have a strong opinion what to codify here. I will let the two of you sort it out. :)

OK. We've agreed that comment style for internal docs doesn't matter, but there should be some thought put into making the comment useful (e.g. talking about constraints on arguments etc.) when they are put there.

@dnoe will own adding proper Doxygen support to the build or stop using Doxygen in his internal comments ;)

Maybe both of those things...