[SKIP CI] doxygen fixes#4509
Merged
lgirdwood merged 3 commits intothesofproject:mainfrom Jul 21, 2021
Merged
Conversation
Remove all the duplicate \file platform/lib/cpu.h. The \file parameter is optional, the duplicates made these entire comments no-ops and spit a lot of warnings. Doxygen knows where the files are. Removed the \file argument in other places as well which fixes a ton of warnings like: sof/src/audio/volume/volume_hifi3.c:7: warning: the name 'audio/volume_hifi3.c' supplied as the argument in the \file statement is not an input file Or: sof/src/lib/pm_runtime.c:7: warning: the name 'lib/pm_runtime.c' supplied as the argument in the \file statement matches the following input files: sof/src/lib/pm_runtime.c sof/src/platform/intel/cavs/lib/pm_runtime.c sof/src/platform/library/lib/pm_runtime.c Please use a more specific name by including a (larger) part of the path! Note these warnings are not seen in the default doxygen configuration which ignores a lot of comments. Signed-off-by: Marc Herbert <marc.herbert@intel.com>
At first I assumed some refactorings forgot to update the comments to match. Then I saw some of these could never had made sense ever. This does not fix _all_ doxygen warnings, it only makes the remaining warnings easy to grep -v. This is just good enough for me to test other doxygen changes without being drown into warning noise. C files are not parsed by the default doxygen configuration - "if it's not tested then it does not work". Signed-off-by: Marc Herbert <marc.herbert@intel.com>
Stop ignoring most comments in the trace.h file. Confusingly, only comments in trace.c were considered because unlike trace.h, trace.c is not turned off by the preprocessor but by CMake instead. Signed-off-by: Marc Herbert <marc.herbert@intel.com>
cujomalainey
approved these changes
Jul 20, 2021
Contributor
cujomalainey
left a comment
There was a problem hiding this comment.
LGTM for crossover, any chance we can have these kind of issues error out in CI?
Collaborator
Author
That would require:
tl;dr: it should be possible but a significant amount of work. Just for the record here's a raw dump of my current config: +GENERATE_XML = NO
+
+# CASE_SENSE_NAMES = NO
+INPUT = @top_srcdir@/src/
EXCLUDE = @top_srcdir@/src/include/sof/audio/MaxxEffect
RECURSIVE = YES
FILE_PATTERNS = *.c *.h
@@ -18,13 +14,21 @@ EXAMPLE_PATH = @top_srcdir@/test
IMAGE_PATH =
QUIET = YES
+DOT_IMAGE_FORMAT = svg
+INTERACTIVE_SVG = YES
+
EXTRACT_ALL = YES
EXTRACT_STATIC = YES
+
WARN_IF_UNDOCUMENTED = NO
-SHOW_INCLUDE_FILES = NO
+# Needs doxygen 1.10
+WARN_IF_INCOMPLETE_DOC = NO
+WARN_NO_PARAMDOC = NO
+
+SHOW_INCLUDE_FILES = YES
JAVADOC_AUTOBRIEF = YES
INHERIT_DOCS = YES
-ENABLED_SECTIONS = ""
+# ENABLED_SECTIONS = ""
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = "__attribute__(x)= " \
@@ -32,10 +36,18 @@ PREDEFINED = "__attribute__(x)= " \
"CONFIG_FORMAT_S32LE=1" \
"CONFIG_TRACE=1"
+SOURCE_BROWSER = YES
+STRIP_CODE_COMMENTS = NO
+
+HAVE_DOT = YES
+
+CALL_GRAPH = YES
+CALLER_GRAPH = YES
+
OPTIMIZE_OUTPUT_FOR_C = YES
TYPEDEF_HIDES_STRUCT = YES
#INPUT_FILTER = inputfilter
#FILTER_SOURCE_FILES = YES
-HTML_TIMESTAMP = NO
+# HTML_TIMESTAMP = NO
|
lgirdwood
approved these changes
Jul 21, 2021
Closed
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
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.
No description provided.