I've published a small FOSS library (link below, but what it does is not very material to this question), on GitHub. It doesn't have releases yet, but it's quite usable and (sort of) tested.
Now, I have a beefy front-page document for the repository - describing design principles, giving some example mini-snippets of code, and describing example programs available in the repository. I also have a 3.75 comment-to-code ratio - but only some of my code has doxygen comments, some of those are partial, and a bunch of information is within the body of functions/methods.
I want to get to a point where I have reference documentationn for my whole library - for every (non-inner) class and every namespace, with search functionality, and perhaps some bells and whistles I can't yet name. I would also like this to be "auto-filled-in" for those parts of the code which I have not spelled out the trivial doxygen comments (
/** adds @p x and @p y \n@param x the left-hand-side number to add \n@param y the right-hand-side number to add \n@return the sum of x and y */).
I've never actually used doxygen before. I mean, I've been writing doxygen-style comments, but I was only reading them as a human or having Eclipse use them for tooltips. I now find myself wondering:
- Should I now just look for the best offline/online document generation tool, or should I do more preparatory work before (and if so, what kind)?
- Regardless of specific tools, should I even consider on-line/dynamically-generated documentation, or should I stick to doing it myself and finding someplace to host it?
General orientation / indications of pitfalls / expected difficulties would be appreciated.
PS - The code is C++ and CUDA (+ a bash script). The repository is here.