Doxygen conversion #722
Doxygen conversion #722
Conversation
Adds initial doxyfile for doxygen configuration. Has some basic settings for getting up and running with decent results. Also, the beautiful doxygen-awesome-css project has been included in the makefile such that we can pull (on your own time) a nice package to make the doxygen output so much prettier to look at than the default.
this commit adds the proper source file directory, so now doxygen picks up all of the C files for processing. Some minor cleanup and file exclusions have also been added such that things like `paq.sh` and sub `Readme.md` files are not picked up.
the difference isnt staggering by any means. the original comment blocks had most everything we needed. More work is required and there are still questions to be had about how much information / styling is desired to be retained in the code comments, verses removing some styling because doxygen handles that conversion into html with styling automatically.
HEADER is the intro API section of the paq'd files, which is the most critical part of our documentation. Ideally, this file needs to stay the same style because it needs to be incorporated into the header file; however, we can make a minor modification to allow doxygen to render it. with this commit, I change the name to HEADER.c to allow doxygen processing. This shouldn't have any affect on the generated paq file. Eventually, I would like to move this HEADER file into a different name and the overall mainpage of the documentation.
nuklear.h has been converted to C89 style comment blocks instead of the amalgamation it was before (presummably a relic of the other documentation system). examples compile. more testing is required.
|
How do we want to handle merging the main Readme.md with the HEADER and nuklear.h API documentation? Do we want to merge that at all? To me, the Readme and the HEADER seem to be doing the same thing and we should combine that into 1 document, or figure out a different responsibility for one or the other. The nuklear.h API documentation seems to be alright, but perhaps too encompassing? I understand that this might have been the best way to get the documentation upfront in the packed header file; so we might just have to keep it. |
|
Doxygen will provide commandline outputs for warnings and errors. This means that we can make documentation part the the CI/CD pipeline. If that is desireable, I would be happy to look into hooking that up. |
|
Currently, The Doxygen will read comments from all of the source c.h files. Is that how we want to do it? or would there be a preference to only scanning the packed header file? |
|
Disclamer: I'm not a maintainer of this repo. These are my personal opinions.
Deduplicate this code. Doxygen has a feature for it IIRC (inclusion or something). Code/doc duplication doesn't make sense.
Yes, it should be.
I think scanning the packed header would be the best and simplest way to generate documentation. The library is used as a single header so the doc should be generated from it too. Last, I think you can replace |
I can definitely get behind this.
i totally agree that we can (and should) make liberal use of the my only concern with using groups is that (although nice) doesn't prevent people (in fact, seems to encourage) from adding functions to specific groups from anywhere in the code base. So, although doxygen will present all of the data in a nice grouped fashion, there is nothing encouraging (or no place to put) these functions in the API header. If Doxygen were the only form of documentation, I would say anything; but seeing that this project also needs to have clean and readible stuff inside the packed header; we might want to stick with the tables? or a combination of both? |
|
Combination of both would be redundant work. Many Doxygen features can be abused and I don't think people would abuse Doxygen's grouping. The library is already significantly consistent (related functions have similar names and are grouped together in code) so it naturally suggests any contributor to continue doing it. The grouping can also be done using |
|
If I have the time, I might branch and do some serious cleanup. Skeleton headers everywhere. Groups. Try to combine files. Maybe build out the docs with more MD files . just see how it turns out. |
Here is an initial attempt at converting the project documentation to Doxygen. I believe in doxygen and I also believe that documentation does not have to be painful. So i am going to try to give just enough information in this PR to get us running, but hopefully whet the appetite for others to read further. There is a lot of configuration options and flexibility within Doxygen, but the defaults are generally pretty good.
Status
This PR has everything that anyone should need to generate the new doxygen output. It is setup for HTML output (see other output options) and includes all of the original documentation, readmes, etc. (I just remembered that I did not add license and changelog); but with the added benefit of tons more information that Doxygen extracts from the code.
Everything should compile just as it was. Please test out everything and make sure the documentation generation works and that the demos work, because modification of the comment blocks was necessary, and I made liberal use of find and replace.
How to Doxygen??
very simple. Every
*.[ch]file that you want documented should start withand every function/method should have a header with the following template
This is very similar to how the documentation was being done before, just with a little less table formatting and a little more keywords.
If you do the template for all of the functions, your documentation will be perfect.
What about other files?
Doxygen supports many different file formats and I suggest you take a look at www.doxygen.nl to see what else is available; however, I believe this project will only need
*.[ch]and*.md; as such, I took the liberty of renaming the HEADER to HEADER.md, as this allows Doxygen to render it correctly (and paq doesn't care).Further reading
Please take a look at the Getting Started page on the doxygen website https://www.doxygen.nl/manual/docblocks.html as it is a fantastic introduction.
Questions?
I am sure there will be plenty of questions, especially given the state of the documentation conversion. I am hoping that this PR can be the place for those questions to be discussed. Please get involved and provide commentary where you feel necessary. I know I will ask some questions right away.