-2

Suppose I'm the first person write a proper Doxygen comment for a source file. Suppose also that there have been multiple contributors to the file - original author, previous maintainers, current maintainers, people who contributed a function, or just a minor one-liner bug fix.

What's an appropriate way to list them (using the @author / @authors doxygen tag), along with their roles? (Or - should I not list their roles?)

einpoklum
  • 2,478
  • 1
  • 13
  • 30
  • 1
    Didn't downvote, but: What are you looking out of having your API documentation include the author name? Do you want their contact information to be advertised so people can contact them with questions? Is it a way of giving them credit? Or is it some other intention? – Alexander Jun 26 '21 at 23:30
  • @Alexander: For credit mostly, I guess. Plus, I want to observe custom. – einpoklum Jun 26 '21 at 23:47
  • 1
    For credit: a project readme might be a better place. It's central, relevant, and much more visible. Can't speak for others, but when I read the API docs to remind myself of the exact name of some method, I don't really give a shit who the author is/was ‍♂️. As far as customs go: have you seen other documentation do this? – Alexander Jun 26 '21 at 23:50

1 Answers1

3

Version control is the best place to find a list of maintainers and contributors. Version control is also the best place to find out why code was changed. It does not matter whether you use Git, Subversion, Mercurial, or any other kind. Changes to files should be tracked by a proper version control system.

This negates the need to list authors in Doxygen comments because version control associates changes with the person who made them. Code comments should explain how to use the code without resorting to reading source code. You can always extract a list of maintainers from the commits in version control. Knowing the author doesn't tell me how to call a function, or for what purpose a certain class exists. Listing authors in comments is an artifact of a bygone era before version control systems were widely-used.

It has been my experience that author roles or job titles have been less important than who made a change, why it was made, and what their email address is so I can contact them if I have questions. I wouldn't worry about roles at all in version control or Doxygen comments.

Greg Burghardt
  • 34,276
  • 8
  • 63
  • 114
  • The contents of a project cannot assume version control; and users (and even developers) typically have just a release, not a version-controlled copy. And while it's true that VC is how you would want to track changes, _credit_ for contribution is something different than that. Finally, I asked about common formatting, not about whether to use a comment for this or not. – einpoklum Jun 27 '21 at 06:35