Unbreak Doxygen configuration #559
Conversation
PROJECT_NAME goes into the title, don't scream with ALL CAPS here. PROJECT_BRIEF also goes into the title. Trailing dots are not used in English titles and do not look good. JAVADOC_AUTOBRIEF set to YES because writing "@brief" is excessive and some members do not use it (resulting in missing short docs). OPTIMIZE_OUTPUT_FOR_C so that we don't have references to classes and things like that. We use Doxygen for Themis Core. TYPEDEF_HIDES_STRUCT set to YES because Themis code style uses typedefs instead of C tags, so we prefer to not mention them. INPUT should include the top-level README file and only Themis Core. USE_MDFILE_AS_MAINPAGE makes sure that README is displayed. FILE_PATTERNS have to be set explicitly, otherwise Doxygen does not see our source code. MACRO_EXPANSION, EXPAND_ONLY_PREDEF, and PREDEFINED are used to hide pervasive API exporting macros from Doxygen output.
Write these macros in a single line so that Doxygen preprocessor strips them and does not break function definitions because of that.
| @@ -154,8 +154,7 @@ themis_status_t themis_secure_message_verify(const uint8_t* public_key, | |||
| * storage then THEMIS_BUFFER_TOO_SMALL will return and wrapped_message_length will store length of | |||
| * buffer needed for wrapped message store | |||
| */ | |||
| DEPRECATED("use 'themis_secure_message_encrypt' with private and public keys to encrypt message, " | |||
| "or 'themis_secure_message_sign' with private key to sign message") | |||
| DEPRECATED("use 'themis_secure_message_encrypt' with private and public keys to encrypt message, or 'themis_secure_message_sign' with private key to sign message") | |||
There was a problem hiding this comment.
doxygen doesn't support multiline macro/function calls?
There was a problem hiding this comment.
Well, not really. It tries really hard to emulate C preprocessor, but sometimes this leads to poor results. Doxygen does preprocessing mostly to exclude parts of the file due to conditional compilation.
Here the THEMIS_API and DEPRECATED macros are considered a part of return type and they get mentioned in function signature, and this breaks Doxygen parser leading to funny output:
Strictly speaking, they are a part of the signature, but we’re not really interested in this when generating API documentation. Thus we’d like to remove both of them.
Enabling EXPAND_ONLY_PREDEF and adding THEMIS_API to PREDEFINED gets rid of it. DEPRECATED macros will be ignored if they are written in one line, thanks to SKIP_FUNCTION_MACROS:
Lines 1987 to 1995 in c8a469f
|
Thank you @ilammy for taking care! Merge 'em all! |
We have a Doxyfile and a lot of Doxygen-compatible comments in Themis codebase. However, they are currently broken. Update Doxyfile and unbreak Doxygen configuration.
Now running
doxygenfrom the project root is actually useful.Before:
After:
It does not look as good as it could, there are many missing files, some docs are not pretty, etc. But at least they can be viewed now and we can work on improvements. Some of the most obnoxious ones are fixed right here.
Checklist
Change is covered by automated tests(it is not)Benchmark results are attached(not applicable)Example projects and code samples are updated if needed(not applicable)Changelog is updated if needed(not applicable)