1

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.

Improve this question
4
  • Sorry, we don't do tool recommendations here. But its great that you're looking into better reference docs for your project! Throughout my programming experience, the lack of detailed references has often meant that I couldn't really make proper use of a library without looking at the implementation and taking a guess which behaviour is part of the contract and will be supported across versions. If you find that Sphinx works fine for you, that's great, though it's certainly an unusual choice when compared to the more common Doxygen. Commented Nov 17, 2016 at 16:18
  • @amon: Thanks for the compliment. I've removed the tool recommendation aspect (I hope), and I think some of the question stands anyway. Commented Nov 17, 2016 at 18:21
  • 1
    If I was you, I'd use doxygen and this tool to generate markdown for your github project's wiki. You could easily automate the whole process because a github wiki is just a git repository of markdown files. Commented Nov 17, 2016 at 18:37
  • 1
    Your edits improved the question, but I think it is still a bit broad and perhaps opinion-based. Maybe you could focus it a bit more? There is some good advice here. Commented Nov 28, 2016 at 16:21

0

Reset to default

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.