From d4024f586216a6bf4e2dfb667df8149b7f95b5c6 Mon Sep 17 00:00:00 2001 From: Chris Luke Date: Tue, 6 Sep 2016 09:32:36 -0400 Subject: 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 --- doxygen/Makefile | 37 ++++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-) (limited to 'doxygen/Makefile') diff --git a/doxygen/Makefile b/doxygen/Makefile index f3ddb2c9..471b6fd7 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 &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 &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)" \ -- cgit 1.2.3-korg