generate documentation using Doxygen #25
Draft
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Just a small taste: refman.pdf 😃 |
This commit adds support to generate documention using the Doxygen tool. Principly this is a straightforward task, however the SaC language has certain properties which do not work well with Doxygen's adherences to C/C++ syntax conventions. Through the included script, sac2doxygen.py, we are able to transform the SaC code into a form that is more suitable for Doxygen. The script either converts or removes certain keywords and statements. Additionally it runs CPP beforehand, expanding all macros - this gives us all function definitions which is more useful when referencing the documentation.
Otherwise we might cause some strange transformation to occur, especially if we have code examples in comments.
We did not handle the negate operator correctly. We also now handle VARGS in return type of functions.
I think this makes more sense, and makes search for code more easily in the docs. Imagine looking for + on Bools (contrived example), using the *_symbol notation this is not possible (as you;d need to remember to search for ADD, not +).
Also there were some interesting macro problems in FixedPoint which should be resolved now.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
We now support generating documentation using the Doxygen tool. Principally this is a straightforward task, however the SaC language has certain properties which do not work well with Doxygen's adherence to C/C++ syntax conventions. The
sac2doxygen.pyscript transforms the SaC into a form that is more easily parsed by Doxygen.This is hugely more advantageous than using
sac2tex, as we are able to more closely link documentation to code. Additionally, we are able to generate all function variants (through theTemplates.macfile) which is not the case when usingsac2tex. We are also able to generate a variety of outputs, either HTML, PDF (LaTeX), MAN-pages, and even publish on ReadTheDocs (this last one is not important).This MR is not complete yet, these steps are still needed: