+1 Standardization of documentation (and requirements to have it) are good.

+1 from me if people can stand writing all that .

+1 on all of this.

I think I'd advocate dropping file-level Doxygen comments entirely, or at least allowing them to be empty when they'd be identical to the description of the only or primary class in the file. We have too many of these right now that don't add any useful information.

Also, if this hasn't been established in our guidelines, I think we should prefer "@" for Doxygen markup rather than "\". As discussed recently somewhere, "\" is parsed by too many other tools, and that can cause confusion.

Thanks Krzysztof Findeisen, this is great! I like your suggestions with Jim Bosch's additions. I don't think we'll be using file-level Doxygen comments in the Pipelines API reference.

Re: version added:

I've seen a lot of projects use 'version added' fields, but most do it quite inconsistently. It seems to only happen when an overall API is very mature, as a way to highlight new APIs or changes to call parameters.

At the same time, we'll be publishing documentation in parallel for each release (and more), so the API reference is really a representation of truth for the specific version of the Stack that are being used. When an API was added is besides the point (deprecation notices are different, since they provide actionable information).

The release notes are the best place to advertise new and changed APIs (in addition to collecting deprecation notices). We've been poor at documenting API changes in our release notes and/or change log (our release notes are mostly at a higher level), but this is a direction we want to go (not yet here in this RFC).

In summary, I can see cases where we'll want to have 'version added' or 'version changed' fields in C++ docs for very tricky and backwards incompatible changes, but for the most part consistent version information should be in release notes/change logs.

The C++ API documentation standards should point out that doxygen comments must be in the .h file. See https://community.lsst.org/t/doxygen-parsing-of-cc-files/1175?u=jsick

Jim Bosch, it's been a couple of years since I've used Doxygen, but IIRC documentation for top level functions and (eew) globals only gets generated if there's a @file comment – otherwise, there's no page to put the function documentation on. Classes don't need a @file, though.

Jonathan Sick, is the "only in headers" already LSST policy (and merely contradicted by the existing guidelines), or is it something being introduced in this RFC? I've never (yet) encountered the bug you linked to, and separating method specs from their definitions does make it harder to implement/maintain the latter.

Re: @since tags, I have found them useful for deciding whether I have access to a feature when I don't have access to old documentation (and it's much easier than searching through the release notes of an indeterminate number of versions), but I won't press the point.

I've just scoured my email for what happened with the policy on whether all Doxygen goes in header files, and it looks like it was formally decided that all new documentation should go in .h files, but it's not clear whether the guidelines were actual updated (it seems like they were from the conversation, but that was back on Trac, and now that page is just a link to Confluence). I'm not sure if old LSST mailing lists are archived somewhere, but this was thread dm-devel #4 with subject "Updating the C++ Standards Doc", dated 10/31/14.

Oh, and if anyone is interesting in tracking down the history here further, that email refers to a TCT meeting on October 5, 2012 (so even that old email thread was trying to reconstruct history), which sadly doesn't have meeting notes in Trac, probably because (according to the email thread) Robyn Allsman wasn't there for that meeting.

A concern: in my original post, I proposed that an alias be added to Doxygen config files to allow a documentation section for exception safety. Given that the discussion Jonathan linked to suggests LSST's Doxygen setup is fairly brittle, do we dare make such configuration changes?

Given that the discussion Jonathan linked to suggests LSST's Doxygen setup is fairly brittle, do we dare make such configuration changes?

I wouldn't let that stand in the way; we can let the RFC be about what we want and what should be obtainable, and if the implementation ticket takes longer because something doesn't work properly, we can treat that as a separate problem.

We seem to have consensus on most things. I'd be happy to resolve the question of alternate keywords by fiat, so the only outstanding issue is the file-level comment block.

I agree with Jim Bosch that file-level comments rarely have useful content, but removing file pages from the documentation means removing any API element that's not a class member. Could we change the rules so that the file comment is required if and only if the class has functions (including auxiliary functions or operators related to a class), and should not be present if the file only declares classes? Or would that make things too confusing and/or inconsistent?

Could we change the rules so that the file comment is required if and only if the class has functions (including auxiliary functions or operators related to a class), and should not be present if the file only declares classes? Or would that make things too confusing and/or inconsistent?

I think this would be okay, though I agree it could make it too easy to forget at times. It sounds like we either have to do that or add a file comment with no content to every file.

Aha, I did some testing and it appears function documentation is still generated, at least in afw. I don't know if this is because namespace documentation (where the generated documentation appears) is configured differently or because header files get verbatim included anyway.

I withdraw my objections to removing @file (though the question may need to be revisited if source inclusion is disabled later on).

Adopting with changes proposed by Jim Bosch and Jonathan Sick.