0

if you are developing and documenting a library.. do you document every single function / data structure from every source file, or just the public ones that appear on the public header??

im leaning to the second option, is this ok?

labotsirc
  • 722
  • 7
  • 21

2 Answers2

1

That depends on whether you ever want to change anything in that library, say, five years from now. In that case, having documentation can come in handy. However, you should somehow separate your "private" documentation from the documentation you provide to users. This can be done by using two separate doxygen configuration files with different INPUTs.

arne
  • 4,514
  • 1
  • 28
  • 47
1

The answer to your question depends on who is going to read the documentation. If the documentation is going to users of your API, it is probably better that you only provided them with documentation for the public interface. As this way they will not be overwhelmed by details that are not relevant to them.

On the other hand if your documentation is to be read by people maintaining the library, it should include documentation on both the public and private code.

Right now I am using a slightly different approach to arne. I have a script which copies the header files needed for the public interface to a separate directory for packaging up. This is necessary anyway for producing releases. The script also copies the Doxyfile configuration to that directory and then runs doxygen on the reduced set of files. That way I have one doxygen configuration file that I use to produce both public and private documentation.

Bowie Owens
  • 2,798
  • 23
  • 20
  • This is a really good idea as long as the "public" and "protected" documentation show the same level of details. I for example like inheritance and collaboration graphs in my own docs, but a user of a library probably doesn't want that. With a reduced set of headers included in the docs, the usefulness of these graphs is reduced, too. – arne Sep 23 '11 at 04:53
  • @arne, I am working on the assumption that the programmers reading the documentation for my API want the same level of detail that I get but only for code that is relevant to them. You can create quite different documentation depending whether docstrings are in a file that is shipped or not. If you need really different documentation, you probably are going to need two config files. I just find the doxygen config files end up getting reasonably complex and two files are likely to end up being out of sync in some important way eventually. – Bowie Owens Sep 30 '11 at 02:32
  • Yeah, that is obviously a problem. So your way is probably the better one in this case. – arne Sep 30 '11 at 06:34