Document the bitfunnel library API about bitfunnel HOT 3 OPEN

Before committing to Doxygen, we should run Doxygen on BitFunnel to see if any of our existing block comments will be interpreted as Doxygen comments. I want to look before we leap, in case there are lots of existing comments that would need to be changed.

from bitfunnel.

What would our documentation policy be? Would we just document stuff that seems likely to be used or just certain interfaces?

from bitfunnel.

I have used Doxygen previously on one of my projects. I will be happy to run it on BitFunnel and link the results for you to view. I can also give you links to Doxygen-generated documentation for other projects, if that would also be helpful to see what the results might look like.

With regard to the documentation policy, we could aim for one of two targets:

• The API as viewed by a user of the engine library (a small percent of the classes/members)
• The class library documentation useful for a potential future contributor

I have no desire for excessive commentary. My preference is mostly minimal descriptive text, but adding somewhat longer commentary where it helps clarify the dependent relationships between classes. I can illustrate this with a few examples if that would be helpful.

Again, my impetus is that I am making notes for myself to aid my understanding, and with a bit of extra effort can incorporate that into the code to help others that might follow.

from bitfunnel.