SerialTransfer icon indicating copy to clipboard operation
SerialTransfer copied to clipboard

API documentation autogenerated by doxygen, available from repo web page

Open PaulBouchier opened this issue 3 years ago • 0 comments

Is your feature request related to a problem? Please describe. Method and variable documentation, while comprehensive, is scattered among .h and .cpp files. I always have to dig for the API. It should be available from a web page, documented with doxygen or the like. At present it is informally documented. You have done so much good documentation, it's a shame for it not to be more accessible.

Describe the solution you'd like The informal documentation should be formatted as doxygen documentation, so API docs can be autogenerated

Describe alternatives you've considered VS Code isn't bad for navigating, but it's still cumbersome

Additional context I think this should be an easy change, and I've converted documentation for the SerialTransfer class to doxygen format, and am willing to contribute reformatting the rest of the documentation into doxygen format. Please review my work on that class and tell me whether you're open to receiving a pull request for complete doxygen documentation. Note: no code was changed, only comments. I added clarifications and content where I thought it appropriate. I am very open to fixes/changes if you feel any of my documentation changes are incorrect/unclear/need improvement.

Instructions for reviewing the documentation:

  1. Check out the doxygen branch from my SerialTransfer fork here: https://github.com/PaulBouchier/SerialTransfer/tree/doxygen
  2. cd docs
  3. doxygen # running doxygen reads Doxyfile in the docs directory & generates html documentation under docs
  4. firefox html/html/index.html
  5. From the main page (which is the README.md), navigate to classes and select the SerialTransfer class. Read the documentation on members, methods, class purpose, etc.

I envision the latest API should be put up on your github repo page somehow, but don't know the standard way to do that yet. But there must be standard ways.

Thanks for your review of this proposed change. I put it on a branch to keep it separate from the other pull request I have out.

PaulBouchier avatar Feb 18 '22 07:02 PaulBouchier