VPP-346 More VPP doc fixes

- Fix issue in Doxy dependency check when nothing needs to be installed.
  'set -e' and plain '[]' logic don't mix well.
- Fix Makefile snafu when building Doxy output for a single file.
- Include only one of vnet/vnet/buffer.c/dpdk_buffer.c in docs depending on
  DPDKness. This could do with some improvement in future, eg to properly
  align the pre-doxy steps with what Doxy does.
- Fix rendering of 'inline' tag in Doxygen by having it interpret
  always_inline as "inline static".
- Bunch of duplicate CLI command structure names that confused docs and may
  one day have caused debugging issues.
- Several other Doxygen syntax issues fixed, like documenting non-existant
  parameters (usually just the wrong parameter name, typos, etc)

Change-Id: Ia8cca545e5de9f8750602bffa3c4548acc8971aa
Signed-off-by: Chris Luke <chrisy@flirble.org>

3 files changed, 48 insertions, 15 deletions

diff --git a/doxygen/Makefile b/doxygen/Makefile
index f3ddb2c991c..471b6fd7f15 100644
--- a/doxygen/Makefile
+++ b/doxygen/Makefile
@@ -40,8 +40,27 @@ DOXY_INPUT ?= \
 	vpp-api \
 	plugins
 
+# Files to exclude, from pre-Doxygen steps, eg because they're
+# selectively compiled.
+# Examples would be to exclude non-DPDK related sources when
+# there's a DPDK equivalent that conflicts.
+# This is specifically for the pre-Doxygen steps; Doxygen uses
+# @cond for this instead.
+DOXY_PRE_EXCLUDE ?= \
+	vlib/vlib/buffer.c
+
+# Generate a regexp for filenames to exclude
+DOXY_PRE_EXCLUDE_REGEXP = ($(subst .,\.,$(shell echo '$(strip $(DOXY_PRE_EXCLUDE))' | sed -e 's/ /|/g')))
+
+# Discover all the directories we might, possibly, maybe, have include files in
 DOXY_INCLUDE_PATH = $(shell set -e; cd $(WS_ROOT); for item in $(DOXY_INPUT); do find $$item -type d; done)
-DOXY_INCLUDE_PATH += $(shell set -e; cpp -v </dev/null 2>&1 | grep -A 1000 '\#include' | awk '/^ /{print $$1}')
+
+# Discover if we have CPP available
+CPP ?= $(shell which cpp)
+ifneq ($(strip $(CPP)),)
+# Add whatever directories CPP normally includes
+DOXY_INCLUDE_PATH += $(shell set -e; $(CPP) -v </dev/null 2>&1 | grep -A 1000 '\#include' | awk '/^ /{print $$1}')
+endif
 
 # Target directory for doxygen output
 DOXY_OUTPUT ?= $(BR)/docs
@@ -67,7 +86,7 @@ ifeq ($(OS_ID),ubuntu)
 		for i in $(DOC_DEB_DEPENDS); do \
 			dpkg-query --show $$i >/dev/null 2>&1 || inst="$$inst $$i"; \
 		done; \
-		[ "$$inst" ] && sudo apt-get $(CONFIRM) $(FORCE) install $$inst
+		if [ "$$inst" ]; then sudo apt-get $(CONFIRM) $(FORCE) install $$inst; fi
 else ifneq ("$(wildcard /etc/redhat-release)","")
 	@sudo yum install $(CONFIRM) $(DOC_RPM_DEPENDS)
 else
@@ -82,8 +101,10 @@ bootstrap-doxygen: $(BR)/.doxygen-bootstrap.ok
 $(BR)/.doxygen-siphon.dep: Makefile
 	set -e; rm -f "$@"; for input in $(DOXY_INPUT); do \
 		find "$(WS_ROOT)/$$input" -type f \
-			\( -name '*.[ch]' -or -name '*.dox' \) \
-			-print | sed -e "s/^/\$$(SIPHON_FILES): /" >> $@; \
+			\( -name '*.[ch]' -or -name '*.dox' \) -print \
+			| grep -v -E '^$(WS_ROOT)/$(DOXY_PRE_EXCLUDE_REGEXP)$$' \
+			| sed -e "s/^/\$$(SIPHON_FILES): /" \
+			>> $@; \
 	done
 
 # Include the source -> siphon dependencies
@@ -93,11 +114,13 @@ $(BR)/.doxygen-siphon.dep: Makefile
 $(SIPHON_FILES): $(DOXY_DIR)/siphon_generate.py $(BR)/.doxygen-bootstrap.ok
 	@rm -rf "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
 	@mkdir -p "$(SIPHON_INPUT)" "$(SIPHON_OUTPUT)"
-	set -e; for input in $(DOXY_INPUT); do \
+	@touch $(SIPHON_INPUT)/files
+	for input in $(DOXY_INPUT); do \
 		cd "$(WS_ROOT)"; \
 		find "$$input" -type f \
-			\( -name '*.[ch]' -or -name '*.dox' \) \
-			-print >> $(SIPHON_INPUT)/files; \
+			\( -name '*.[ch]' -or -name '*.dox' \) -print \
+			| grep -v -E '^$(DOXY_PRE_EXCLUDE_REGEXP)$$' \
+			>> $(SIPHON_INPUT)/files; \
 	done
 	set -e; cd "$(WS_ROOT)"; $(DOXY_DIR)/siphon_generate.py \
 		--output="$(SIPHON_INPUT)" \
diff --git a/doxygen/doxygen.cfg b/doxygen/doxygen.cfg
index 4eb0f373049..971a159502c 100644
--- a/doxygen/doxygen.cfg
+++ b/doxygen/doxygen.cfg
@@ -644,7 +644,7 @@ GENERATE_DEPRECATEDLIST= YES
 # sections, marked by \if <section_label> ... \endif and \cond <section_label>
 # ... \endcond blocks.
 
-ENABLED_SECTIONS       =
+ENABLED_SECTIONS       = DPDK
 
 # The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the
 # initial value of a variable or macro / define can have for it to appear in the
@@ -2061,7 +2061,8 @@ PREDEFINED             = \
 	__ORDER_LITTLE_ENDIAN__=1234 \
 	__BYTE_ORDER__=1234 \
 	__FLOAT_WORD_ORDER__=1234 \
-	DPDK=1
+	DPDK=1 \
+	always_inline:="static inline"
 	
 # 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
diff --git a/doxygen/siphon_generate.py b/doxygen/siphon_generate.py
index 457757b510c..8b999114e52 100755
--- a/doxygen/siphon_generate.py
+++ b/doxygen/siphon_generate.py
@@ -80,6 +80,21 @@ def count_braces(str, count=0, found=False):
 # Collated output for each siphon
 output = {}
 
+# Build a list of known siphons
+known_siphons = []
+for item in siphon_patterns:
+	siphon = item[1]
+	if siphon not in known_siphons:
+		known_siphons.append(siphon)
+
+# Setup information for siphons we know about
+for siphon in known_siphons:
+	output[siphon] = {
+            "file": "%s/%s.siphon" % (args.output, siphon),
+            "global": {},
+            "items": [],
+        }
+
 # Pre-process file names in case they indicate a file with
 # a list of files
 files = []
@@ -233,12 +248,6 @@ for filename in files:
             if close_siphon is not None:
                 # Write the siphoned contents to the right place
                 siphon_name = close_siphon[0]
-                if siphon_name not in output:
-                    output[siphon_name] = {
-                        "global": {},
-                        "items": [],
-                        "file": "%s/%s.siphon" % (args.output, close_siphon[0])
-                    }
 
                 # Copy directives for the file
                 details = {}