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.

closed as off-topic by gnat, amon, Greg Burghardt, Robert Harvey, dan04 Nov 17 '16 at 18:07

This question appears to be off-topic. The users who voted to close gave this specific reason:

  • "Questions asking us to find or recommend tools, libraries, programming languages, resources (including books, blogs, tutorials, and examples), or projects to undertake are off-topic here as they attract opinionated answers that won't have lasting value to others. You may be able to get help in The Whiteboard, our chat room." – gnat, amon, Greg Burghardt, Robert Harvey, dan04
If this question can be reworded to fit the rules in the help center, please edit the question.

  • 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. – amon Nov 17 '16 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. – einpoklum Nov 17 '16 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. – RubberDuck Nov 17 '16 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. – user22815 Nov 28 '16 at 16:21