diff options
author | 2016-09-06 09:32:36 -0400 | |
---|---|---|
committer | 2016-09-06 20:35:28 +0000 | |
commit | d4024f586216a6bf4e2dfb667df8149b7f95b5c6 (patch) | |
tree | b8150f25da5e7b79ce119f8996fda1bd037dc0df | |
parent | 7394b5b06b6549b5ff7fe3f1103c269ae966f584 (diff) |
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>
-rw-r--r-- | doxygen/Makefile | 37 | ||||
-rw-r--r-- | doxygen/doxygen.cfg | 5 | ||||
-rwxr-xr-x | doxygen/siphon_generate.py | 21 | ||||
-rw-r--r-- | vlib/vlib/buffer.c | 8 | ||||
-rw-r--r-- | vlib/vlib/buffer_funcs.h | 4 | ||||
-rw-r--r-- | vlib/vlib/counter.h | 4 | ||||
-rw-r--r-- | vlib/vlib/dpdk_buffer.c | 8 | ||||
-rw-r--r-- | vlib/vlib/vlib_process_doc.h | 6 | ||||
-rw-r--r-- | vnet/vnet/classify/policer_classify.c | 2 | ||||
-rw-r--r-- | vnet/vnet/devices/dpdk/node.c | 4 | ||||
-rw-r--r-- | vnet/vnet/ip/ip6_forward.c | 4 | ||||
-rw-r--r-- | vnet/vnet/ip/ip_feature_registration.c | 4 | ||||
-rw-r--r-- | vnet/vnet/ipsec-gre/node.c | 6 | ||||
-rw-r--r-- | vnet/vnet/unix/pcap.c | 11 | ||||
-rw-r--r-- | vnet/vnet/unix/tapcli.c | 8 | ||||
-rw-r--r-- | vnet/vnet/vxlan-gpe/decap.c | 2 | ||||
-rw-r--r-- | vppinfra/vppinfra/bihash_8_8.h | 2 | ||||
-rw-r--r-- | vppinfra/vppinfra/bihash_doc.h | 2 | ||||
-rw-r--r-- | vppinfra/vppinfra/bitmap.h | 8 |
19 files changed, 99 insertions, 47 deletions
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 </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 4eb0f373..971a1595 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 457757b5..8b999114 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 = {} diff --git a/vlib/vlib/buffer.c b/vlib/vlib/buffer.c index 84cecc27..e1be2005 100644 --- a/vlib/vlib/buffer.c +++ b/vlib/vlib/buffer.c @@ -37,6 +37,13 @@ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/** + * @cond (!DPDK) + * @file + * + * Allocate/free network buffers. + */ + #include <vlib/vlib.h> uword @@ -1527,6 +1534,7 @@ VLIB_CLI_COMMAND (show_buffers_command, static) = { }; /* *INDENT-ON* */ +/** @endcond */ /* * fd.io coding-style-patch-verification: ON * diff --git a/vlib/vlib/buffer_funcs.h b/vlib/vlib/buffer_funcs.h index 8b80be16..497a6bb0 100644 --- a/vlib/vlib/buffer_funcs.h +++ b/vlib/vlib/buffer_funcs.h @@ -75,7 +75,7 @@ vlib_get_buffer (vlib_main_t * vm, u32 buffer_index) /** \brief Translate buffer pointer into buffer index @param vm - (vlib_main_t *) vlib main data structure pointer - @param b - (void *) buffer pointer + @param p - (void *) buffer pointer @return - (u32) buffer index */ always_inline u32 @@ -135,7 +135,7 @@ vlib_buffer_index_length_in_chain (vlib_main_t * vm, u32 bi) /** \brief Copy buffer contents to memory @param vm - (vlib_main_t *) vlib main data structure pointer - @param bi - (u32) buffer index + @param buffer_index - (u32) buffer index @param contents - (u8 *) memory, <strong>must be large enough</strong> @return - (uword) length of buffer chain */ diff --git a/vlib/vlib/counter.h b/vlib/vlib/counter.h index 28686b4b..a7903206 100644 --- a/vlib/vlib/counter.h +++ b/vlib/vlib/counter.h @@ -168,7 +168,7 @@ typedef struct } vlib_counter_t; /** Add two combined counters, results in the first counter - @param [in/out] a - (vlib_counter_t *) dst counter + @param [in,out] a - (vlib_counter_t *) dst counter @param b - (vlib_counter_t *) src counter */ @@ -180,7 +180,7 @@ vlib_counter_add (vlib_counter_t * a, vlib_counter_t * b) } /** Subtract combined counters, results in the first counter - @param [in/out] a - (vlib_counter_t *) dst counter + @param [in,out] a - (vlib_counter_t *) dst counter @param b - (vlib_counter_t *) src counter */ always_inline void diff --git a/vlib/vlib/dpdk_buffer.c b/vlib/vlib/dpdk_buffer.c index 828bc81f..e617be2a 100644 --- a/vlib/vlib/dpdk_buffer.c +++ b/vlib/vlib/dpdk_buffer.c @@ -37,6 +37,13 @@ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/** + * @cond DPDK + * @file + * + * Allocate/free network buffers with DPDK. + */ + #include <rte_config.h> #include <rte_common.h> @@ -1398,6 +1405,7 @@ buffer_state_validation_init (vlib_main_t * vm) VLIB_INIT_FUNCTION (buffer_state_validation_init); #endif +/** @endcond */ /* * fd.io coding-style-patch-verification: ON * diff --git a/vlib/vlib/vlib_process_doc.h b/vlib/vlib/vlib_process_doc.h index 43a51b57..a47c5e4b 100644 --- a/vlib/vlib/vlib_process_doc.h +++ b/vlib/vlib/vlib_process_doc.h @@ -57,8 +57,8 @@ Here's an example: - <pre> - #define EXAMPLE_POLL_PERIOD 10.0 + <code><pre> + \#define EXAMPLE_POLL_PERIOD 10.0 static uword example_process (vlib_main_t * vm, vlib_node_runtime_t * rt, @@ -120,7 +120,7 @@ .type = VLIB_NODE_TYPE_PROCESS, .name = "example-process", }; - </pre> + </pre></code> In this example, the VLIB process node waits for an event to occur, or for 10 seconds to elapse. The code demuxes on the event diff --git a/vnet/vnet/classify/policer_classify.c b/vnet/vnet/classify/policer_classify.c index e4580a20..498f83b5 100644 --- a/vnet/vnet/classify/policer_classify.c +++ b/vnet/vnet/classify/policer_classify.c @@ -161,7 +161,7 @@ set_policer_classify_command_fn (vlib_main_t * vm, return 0; } -VLIB_CLI_COMMAND (set_input_acl_command, static) = { +VLIB_CLI_COMMAND (set_policer_classify_command, static) = { .path = "set policer classify", .short_help = "set policer classify interface <int> [ip4-table <index>]\n" diff --git a/vnet/vnet/devices/dpdk/node.c b/vnet/vnet/devices/dpdk/node.c index 7b2914a8..54a6a503 100644 --- a/vnet/vnet/devices/dpdk/node.c +++ b/vnet/vnet/devices/dpdk/node.c @@ -660,9 +660,9 @@ poll_rate_limit (dpdk_main_t * dm) b->current_length </code> and dispatch directly to ip4-input-no-checksum, or ip6-input. Trace the packet if required. - @param vm vlib_main_t corresponding to the current thread + @param vm vlib_main_t corresponding to the current thread @param node vlib_node_runtime_t - @param frame vlib_frame_t input-node, not used. + @param f vlib_frame_t input-node, not used. @par Graph mechanics: buffer metadata, next index usage diff --git a/vnet/vnet/ip/ip6_forward.c b/vnet/vnet/ip/ip6_forward.c index b076ed04..c9779602 100644 --- a/vnet/vnet/ip/ip6_forward.c +++ b/vnet/vnet/ip/ip6_forward.c @@ -3297,7 +3297,7 @@ add_del_ip6_interface_table (vlib_main_t * vm, return error; } -VLIB_CLI_COMMAND (set_interface_ip_table_command, static) = { +VLIB_CLI_COMMAND (set_interface_ip6_table_command, static) = { .path = "set interface ip6 table", .function = add_del_ip6_interface_table, .short_help = "set interface ip6 table <intfc> <table-id>" @@ -3442,7 +3442,7 @@ show_ip6_local_command_fn (vlib_main_t * vm, -VLIB_CLI_COMMAND (show_ip_local, static) = { +VLIB_CLI_COMMAND (show_ip6_local, static) = { .path = "show ip6 local", .function = show_ip6_local_command_fn, .short_help = "Show ip6 local protocol table", diff --git a/vnet/vnet/ip/ip_feature_registration.c b/vnet/vnet/ip/ip_feature_registration.c index baf7ea27..9505a09e 100644 --- a/vnet/vnet/ip/ip_feature_registration.c +++ b/vnet/vnet/ip/ip_feature_registration.c @@ -39,7 +39,7 @@ feature subgraph arc, which needs to run before @c ip4-lookup. In either base code or a plugin, <CODE><PRE> - #include <vnet/ip/ip_feature_registration.h> + \#include <vnet/ip/ip_feature_registration.h> </PRE></CODE> and add the new feature as shown: @@ -57,7 +57,7 @@ @c my-ip4-unicast-feature on an interface: <CODE><PRE> - ip4_main_t *im = &ip4_main; + ip4_main_t *im = \&ip4_main; ip_lookup_main_t *lm = &im->lookup_main; ip_config_main_t *rx_cm = &lm->feature_config_mains[VNET_IP_RX_UNICAST_FEAT]; diff --git a/vnet/vnet/ipsec-gre/node.c b/vnet/vnet/ipsec-gre/node.c index 5a176088..d20f248a 100644 --- a/vnet/vnet/ipsec-gre/node.c +++ b/vnet/vnet/ipsec-gre/node.c @@ -62,9 +62,9 @@ u8 * format_ipsec_gre_rx_trace (u8 * s, va_list * args) * * This node remove GRE header. * - * @param vm vlib_main_t corresponding to the current thread. - * @param node vlib_node_runtime_t data for this node. - * @param frame vlib_frame_t whose contents should be dispatched. + * @param vm vlib_main_t corresponding to the current thread. + * @param node vlib_node_runtime_t data for this node. + * @param from_frame vlib_frame_t whose contents should be dispatched. * * @par Graph mechanics: buffer metadata, next index usage * diff --git a/vnet/vnet/unix/pcap.c b/vnet/vnet/unix/pcap.c index 5c8a14bd..bba225f7 100644 --- a/vnet/vnet/unix/pcap.c +++ b/vnet/vnet/unix/pcap.c @@ -43,21 +43,24 @@ /** * @file * @brief PCAP function. - * Usage * - * #include <vnet/unix/pcap.h> + * Usage: + * + * <code><pre> + * \#include <vnet/unix/pcap.h> * * static pcap_main_t pcap = { * .file_name = "/tmp/ip4", * .n_packets_to_capture = 2, * .packet_type = PCAP_PACKET_TYPE_ip, * }; + * </pre></code> * * To add a buffer: * - * pcap_add_buffer (&pcap, vm, pi0, 128); + * <code><pre>pcap_add_buffer (&pcap, vm, pi0, 128);</pre></code> * - * File will be written after n_packets_to_capture or call to pcap_write (&pcap). + * File will be written after @c n_packets_to_capture or call to pcap_write (&pcap). * */ diff --git a/vnet/vnet/unix/tapcli.c b/vnet/vnet/unix/tapcli.c index 608b2209..c2328f0d 100644 --- a/vnet/vnet/unix/tapcli.c +++ b/vnet/vnet/unix/tapcli.c @@ -802,10 +802,10 @@ static tapcli_interface_t *tapcli_get_new_tapif() /** * @brief Connect a TAP interface * - * @param *vm - vlib_main_t - * @param *intfc_name - u8 - * @param *hwaddr_arg - u8 - * @param *sw_if_index - u32 + * @param vm - vlib_main_t + * @param intfc_name - u8 + * @param hwaddr_arg - u8 + * @param sw_if_indexp - u32 * * @return rc - int * diff --git a/vnet/vnet/vxlan-gpe/decap.c b/vnet/vnet/vxlan-gpe/decap.c index 70cf08e1..7eca3f6b 100644 --- a/vnet/vnet/vxlan-gpe/decap.c +++ b/vnet/vnet/vxlan-gpe/decap.c @@ -96,7 +96,7 @@ static u8 * format_vxlan_gpe_with_length (u8 * s, va_list * args) * @param *vm * @param *node * @param *from_frame - * @param ip_ip4 + * @param is_ip4 * * @return from_frame->n_vectors * diff --git a/vppinfra/vppinfra/bihash_8_8.h b/vppinfra/vppinfra/bihash_8_8.h index b5f4e3bf..9b5da5a2 100644 --- a/vppinfra/vppinfra/bihash_8_8.h +++ b/vppinfra/vppinfra/bihash_8_8.h @@ -54,7 +54,7 @@ clib_bihash_hash_8_8 (clib_bihash_kv_8_8_t * v) /** Format a clib_bihash_kv_8_8_t instance @param s - u8 * vector under construction - @param v (vararg) - the (key,value) pair to format + @param args (vararg) - the (key,value) pair to format @return s - the u8 * vector under construction */ static inline u8 * diff --git a/vppinfra/vppinfra/bihash_doc.h b/vppinfra/vppinfra/bihash_doc.h index da3d0a9b..e6ab9db6 100644 --- a/vppinfra/vppinfra/bihash_doc.h +++ b/vppinfra/vppinfra/bihash_doc.h @@ -108,7 +108,7 @@ void clib_bihash_free (clib_bihash * h); /** Add or delete a (key,value) pair from a bi-hash table @param h - the bi-hash table to search - @param add_kv - the (key,value) pair to add + @param add_v - the (key,value) pair to add @param is_add - add=1, delete=0 @returns 0 on success, < 0 on error @note This function will replace an existing (key,value) pair if the diff --git a/vppinfra/vppinfra/bitmap.h b/vppinfra/vppinfra/bitmap.h index 4c27820d..9e1ae493 100644 --- a/vppinfra/vppinfra/bitmap.h +++ b/vppinfra/vppinfra/bitmap.h @@ -81,7 +81,7 @@ clib_bitmap_is_equal (uword * a, uword * b) } /** Duplicate a bitmap - @param ai - pointer to a bitmap + @param v - pointer to a bitmap @returns a duplicate of the bitmap */ #define clib_bitmap_dup(v) vec_dup(v) @@ -158,9 +158,9 @@ clib_bitmap_set_no_check (uword * a, uword i, uword new_value) /** Sets the ith bit of a bitmap to new_value Removes trailing zeros from the bitmap - @param a - pointer to the bitmap + @param ai - pointer to the bitmap @param i - the bit position to interrogate - @param new_value - new value for the bit + @param value - new value for the bit @returns the old value of the bit */ always_inline uword * @@ -588,7 +588,7 @@ _(andnoti, a = a & ~b, 1) _(ori, a = a | b, 0) _(xori, a = a ^ b, 1) /** Return a random bitmap of the requested length @param ai - pointer to the destination bitmap @param n_bits - number of bits to allocate - @param [in/out] seed - pointer to the random number seed + @param [in,out] seed - pointer to the random number seed @returns a reasonably random bitmap based. See random.h. */ always_inline uword * |