Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Unbreak Doxygen configuration #559

Merged
merged 4 commits into from
Dec 4, 2019
Merged

Unbreak Doxygen configuration #559

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
eed5dde
Unbreak Doxygen configuration
ilammy Dec 3, 2019
b79c8db
Doxygen-friendly deprecations
ilammy Dec 3, 2019
13126ab
CircleCI, please test Android build
ilammy Dec 4, 2019
a73c803
Merge branch 'master' into doxygen
ilammy Dec 4, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions Doxyfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8
# title of most generated pages and in a few other places.
# The default value is: My Project.

PROJECT_NAME = "THEMIS"
PROJECT_NAME = Themis

# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
# could be handy for archiving the generated documentation or if some version
Expand All @@ -44,7 +44,7 @@ PROJECT_NUMBER =
# for a project that appears at the top of each page and should give viewer a
# quick idea about the purpose of the project. Keep the description short.

PROJECT_BRIEF = "Data security library for network communication and data storage."
PROJECT_BRIEF = "Data security library for network communication and data storage"

# With the PROJECT_LOGO tag one can specify an logo or icon that is included in
# the documentation. The maximum height of the logo should not exceed 55 pixels
Expand Down Expand Up @@ -177,7 +177,7 @@ SHORT_NAMES = NO
# description.)
# The default value is: NO.

JAVADOC_AUTOBRIEF = NO
JAVADOC_AUTOBRIEF = YES

# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first
# line (until the first dot) of a Qt-style comment as the brief description. If
Expand Down Expand Up @@ -242,7 +242,7 @@ TCL_SUBST =
# members will be omitted, etc.
# The default value is: NO.

OPTIMIZE_OUTPUT_FOR_C = NO
OPTIMIZE_OUTPUT_FOR_C = YES

# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
# Python sources only. Doxygen will then generate output that is more tailored
Expand Down Expand Up @@ -382,7 +382,7 @@ INLINE_SIMPLE_STRUCTS = NO
# types are typedef'ed and only the typedef is referenced, never the tag name.
# The default value is: NO.

TYPEDEF_HIDES_STRUCT = NO
TYPEDEF_HIDES_STRUCT = YES

# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This
# cache is used to resolve symbols given their name and scope. Since this can be
Expand Down Expand Up @@ -753,7 +753,7 @@ WARN_LOGFILE =
# spaces.
# Note: If this tag is empty the current directory is searched.

INPUT = src
INPUT = README.md src/soter src/themis

# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
Expand All @@ -773,7 +773,7 @@ INPUT_ENCODING = UTF-8
# *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf,
# *.qsf, *.as and *.js.

FILE_PATTERNS =
FILE_PATTERNS = *.c *.h

# The RECURSIVE tag can be used to specify whether or not subdirectories should
# be searched for input files as well.
Expand Down Expand Up @@ -889,7 +889,7 @@ FILTER_SOURCE_PATTERNS =
# (index.html). This can be useful if you have a project on for instance GitHub
# and want to reuse the introduction page also for the doxygen output.

USE_MDFILE_AS_MAINPAGE =
USE_MDFILE_AS_MAINPAGE = README.md

#---------------------------------------------------------------------------
# Configuration options related to source browsing
Expand Down Expand Up @@ -1933,15 +1933,15 @@ ENABLE_PREPROCESSING = YES
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.

MACRO_EXPANSION = NO
MACRO_EXPANSION = YES

# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
# the macro expansion is limited to the macros specified with the PREDEFINED and
# EXPAND_AS_DEFINED tags.
# The default value is: NO.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.

EXPAND_ONLY_PREDEF = NO
EXPAND_ONLY_PREDEF = YES

# If the SEARCH_INCLUDES tag is set to YES the includes files in the
# INCLUDE_PATH will be searched if a #include is found.
Expand Down Expand Up @@ -1973,7 +1973,7 @@ INCLUDE_FILE_PATTERNS =
# recursively expanded use the := operator instead of the = operator.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.

PREDEFINED =
PREDEFINED = THEMIS_API SOTER_API

# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
# tag can be used to specify a list of macro names that should be expanded. The
Expand Down
6 changes: 2 additions & 4 deletions src/themis/secure_message.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

doxygen doesn't support multiline macro/function calls?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Screen Shot 2019-12-03 at 16 46 00

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:

themis/Doxyfile

Lines 1987 to 1995 in c8a469f

# If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
# remove all references to function-like macros that are alone on a line, have
# an all uppercase name, and do not end with a semicolon. Such function macros
# are typically used for boiler-plate code, and will confuse the parser if not
# removed.
# The default value is: YES.
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
SKIP_FUNCTION_MACROS = YES

THEMIS_API
themis_status_t themis_secure_message_wrap(const uint8_t* private_key,
size_t private_key_length,
Expand All @@ -182,8 +181,7 @@ themis_status_t themis_secure_message_wrap(const uint8_t* private_key,
* THEMIS_BUFFER_TOO_SMALL will return and message_length will store length of buffer needed for
* plain message store
*/
DEPRECATED("use 'themis_secure_message_decrypt' with private and public key to decrypt message or "
"'themis_secure_message_verify' with public key to verify signed message")
DEPRECATED("use 'themis_secure_message_decrypt' with private and public key to decrypt message or 'themis_secure_message_verify' with public key to verify signed message")
THEMIS_API
themis_status_t themis_secure_message_unwrap(const uint8_t* private_key,
size_t private_key_length,
Expand Down