Skip to contentSkip to conversation

doc from doxygen

PATCH In review Thomas Monjalon 2 participants 7 messages Apr 19, 2013 – Apr 26, 2013 2 messages not in the archive

lore
Share & tools
lore
#0 lore raw

cover doc from doxygen

These patches aims to generate a documentation for API from doxygen.

Thomas Monjalon (4):
lib: fix some doxygen comments
mk: factorize some rules
mk: clean dead doc rules
doc: generate HTML for API with doxygen

 doc/doxy-api-index.md                          |  101 +++++++++++++++++++
 doc/doxy-api.conf                              |   59 +++++++++++
 doc/doxy-html-custom.sh                        |    6 ++
 lib/librte_eal/common/include/rte_debug.h      |    2 +-
 lib/librte_eal/common/include/rte_pci.h        |    4 +-
 lib/librte_eal/common/include/rte_string_fns.h |    4 +-
 lib/librte_ether/rte_ethdev.h                  |    6 +-
 mk/rte.doc.mk                                  |  127 ------------------------
 mk/rte.sdkdoc.mk                               |   52 ++++------
 mk/rte.sdkroot.mk                              |   72 ++++----------
 10 files changed, 213 insertions(+), 220 deletions(-)
 create mode 100644 doc/doxy-api-index.md
 create mode 100644 doc/doxy-api.conf
 create mode 100755 doc/doxy-html-custom.sh
 delete mode 100644 mk/rte.doc.mk

A message that is not in the archive (sent off-list or not yet received): cover.1366390454.git.thomas.monjalon-pdR9zngts4EAvxtiuMwx3w@public.gmane.org

#2 lore raw

PATCH 1/4 lib: fix some doxygen comments

- rte_panic must be before rte_panic_ to be associated to its doc
- marker /**< must be used when commenting after the declaration only
- fix rte_string_fns.h title
- typos

---
 lib/librte_eal/common/include/rte_debug.h      |    2 +-
 lib/librte_eal/common/include/rte_pci.h        |    4 ++--
 lib/librte_eal/common/include/rte_string_fns.h |    4 ++--
 lib/librte_ether/rte_ethdev.h                  |    6 +++---
 4 files changed, 8 insertions(+), 8 deletions(-)
lib/librte_eal/common/include/rte_debug.h +1 -1
index 1936dde..dc0fc7f 100644
@@ -77,8 +77,8 @@ void rte_dump_registers(void);
  * @param args
  *   The variable list of arguments.
  */
-#define rte_panic_(func, format, ...) __rte_panic(func, format "%.0s", __VA_ARGS__)
 #define rte_panic(...) rte_panic_(__func__, __VA_ARGS__, "dummy")
+#define rte_panic_(func, format, ...) __rte_panic(func, format "%.0s", __VA_ARGS__)
 
 /*
  * Provide notification of a critical non-recoverable error and stop.
lib/librte_eal/common/include/rte_pci.h +2 -2
index 1007f51..c3937f0 100644
@@ -153,9 +153,9 @@ struct rte_pci_driver {
 	uint32_t drv_flags;                     /**< Flags contolling handling of device. */
 };
 
-/**< Device needs igb_uio kernel module */
+/** Device needs igb_uio kernel module */
 #define RTE_PCI_DRV_NEED_IGB_UIO 0x0001
-/**< Device driver must be registered several times until failure */
+/** Device driver must be registered several times until failure */
 #define RTE_PCI_DRV_MULTIPLE 0x0002
 
 /**
lib/librte_eal/common/include/rte_string_fns.h +2 -2
index da3a3c9..2a366da 100644
@@ -36,7 +36,7 @@
 /**
  * @file
  *
- * Definitions of warnings for use of various insecure functions
+ * String-related functions as replacement for libc equivalents
  */
 
 #ifndef _RTE_STRING_FNS_H_
@@ -106,7 +106,7 @@ einval_error:
  * Takes string "string" parameter and splits it at character "delim"
  * up to maxtokens-1 times - to give "maxtokens" resulting tokens. Like
  * strtok or strsep functions, this modifies its input string, by replacing
- * instances of "delim" with '\0'. All resultant tokens are returned in the
+ * instances of "delim" with '\\0'. All resultant tokens are returned in the
  * "tokens" array which must have enough entries to hold "maxtokens".
  *
  * @param string
lib/librte_ether/rte_ethdev.h +3 -3
index 86477e0..5985496 100644
@@ -400,9 +400,9 @@ struct rte_fdir_conf {
 	enum rte_fdir_mode mode; /**< Flow Director mode. */
 	enum rte_fdir_pballoc_type pballoc; /**< Space for FDIR filters. */
 	enum rte_fdir_status_mode status;  /**< How to report FDIR hash. */
-	/* Offset of flexbytes field in RX packets (in 16-bit word units). */
+	/** Offset of flexbytes field in RX packets (in 16-bit word units). */
 	uint8_t flexbytes_offset;
-	/* RX queue of packets matching a "drop" filter in perfect mode. */
+	/** RX queue of packets matching a "drop" filter in perfect mode. */
 	uint8_t drop_queue;
 };
 
@@ -410,7 +410,7 @@ struct rte_fdir_conf {
  *  Possible l4type of FDIR filters.
  */
 enum rte_l4type {
-	RTE_FDIR_L4TYPE_NONE = 0,       /**< Nnoe. */
+	RTE_FDIR_L4TYPE_NONE = 0,       /**< None. */
 	RTE_FDIR_L4TYPE_UDP,            /**< UDP. */
 	RTE_FDIR_L4TYPE_TCP,            /**< TCP. */
 	RTE_FDIR_L4TYPE_SCTP,     	/**< SCTP. */
Signature · 1 line
1.7.10.4
#3 lore raw

PATCH 2/4 mk: factorize some rules

In reply to a message not in the archive

rte.sdkroot.mk is mainly calling other makefiles. These redirecting rules can be factorized by called makefile.

---
 mk/rte.sdkroot.mk |   68 ++++++++++++++---------------------------------------
 1 file changed, 18 insertions(+), 50 deletions(-)
mk/rte.sdkroot.mk +18 -50
index 5b87b68..6221bec 100644
@@ -89,63 +89,31 @@ default: all
 
 .PHONY: config
 config:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkconfig.mk config
+	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkconfig.mk $@
 
-.PHONY: test
-test:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdktest.mk test
-
-.PHONY: fast_test ring_test mempool_test
-fast_test ring_test mempool_test:
+.PHONY: test fast_test ring_test mempool_test
+test fast_test ring_test mempool_test:
 	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdktest.mk $@
 
-.PHONY: testall
-testall:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdktestall.mk testall
-
-.PHONY: testimport
-testimport:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdktestall.mk testimport
-
-.PHONY: install
-install:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkinstall.mk install
-
-.PHONY: uninstall
-uninstall:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkinstall.mk uninstall
-
-.PHONY: doc
-doc:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk doc
-
-.PHONY: pdfdoc
-pdfdoc:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk pdfdoc
-
-.PHONY: doxydoc
-doxydoc:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk doxydoc
-
-.PHONY: docclean
-docclean:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk docclean
+.PHONY: testall testimport
+testall testimport:
+	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdktestall.mk $@
 
-.PHONY: depdirs
-depdirs:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdepdirs.mk depdirs
+.PHONY: install uninstall
+install uninstall:
+	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkinstall.mk $@
 
-.PHONY: depgraph
-depgraph:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdepdirs.mk depgraph
+.PHONY: doc pdfdoc doxydoc docclean
+doc pdfdoc doxydoc docclean:
+	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk $@
 
-.PHONY: gcovclean
-gcovclean:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkgcov.mk gcovclean
+.PHONY: depdirs depgraph
+depdirs depgraph:
+	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdepdirs.mk $@
 
-.PHONY: gcov
-gcov:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkgcov.mk gcov
+.PHONY: gcov gcovclean
+gcov gcovclean:
+	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkgcov.mk $@
 
 .PHONY: help
 help:
Signature · 1 line
1.7.10.4
#4 lore raw

PATCH 3/4 mk: clean dead doc rules

In reply to a message not in the archive

It seems that doc/ has been removed so these rules are useless. This clean-up is preliminary to generate some doc.

---
 mk/rte.doc.mk     |  127 -----------------------------------------------------
 mk/rte.sdkdoc.mk  |   33 +-------------
 mk/rte.sdkroot.mk |    9 +---
 3 files changed, 4 insertions(+), 165 deletions(-)
 delete mode 100644 mk/rte.doc.mk
mk/rte.doc.mk deleted +0 -127
deleted file mode 100644
index b57504a..0000000
@@ -1,127 +0,0 @@
-#   BSD LICENSE
-# 
-#   Copyright(c) 2010-2012 Intel Corporation. All rights reserved.
-#   All rights reserved.
-# 
-#   Redistribution and use in source and binary forms, with or without 
-#   modification, are permitted provided that the following conditions 
-#   are met:
-# 
-#     * Redistributions of source code must retain the above copyright 
-#       notice, this list of conditions and the following disclaimer.
-#     * Redistributions in binary form must reproduce the above copyright 
-#       notice, this list of conditions and the following disclaimer in 
-#       the documentation and/or other materials provided with the 
-#       distribution.
-#     * Neither the name of Intel Corporation nor the names of its 
-#       contributors may be used to endorse or promote products derived 
-#       from this software without specific prior written permission.
-# 
-#   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
-#   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
-#   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
-#   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 
-#   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
-#   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
-#   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
-#   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 
-#   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
-#   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
-#   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-# 
-#  version: DPDK.L.1.2.3-3
-
-DEFAULT_DPI ?= 300
-
-ifeq ($(BASEDOCDIR),)
-$(error "must be called from RTE root Makefile")
-endif
-ifeq ($(DOCDIR),)
-$(error "must be called from RTE root Makefile")
-endif
-
-VPATH = $(abspath $(BASEDOCDIR)/$(DOCDIR))
-
-pngfiles = $(patsubst %.svg,%.png,$(SVG))
-pdfimgfiles = $(patsubst %.svg,%.pdf,$(SVG))
-htmlfiles = $(patsubst %.rst,%.html,$(RST))
-pdffiles = $(patsubst %.rst,%.pdf,$(RST))
-
-.PHONY: all doc clean
-
-compare = $(strip $(subst $(1),,$(2)) $(subst $(2),,$(1)))
-dirname = $(patsubst %/,%,$(dir $1))
-
-# windows only: this is needed for native programs that do not handle
-# unix-like paths on win32
-ifdef COMSPEC
-winpath = "$(shell cygpath --windows $(abspath $(1)))"
-else
-winpath = $(1)
-endif
-
-all doc: $(pngfiles) $(htmlfiles) $(pdffiles) $(DIRS)
-	@true
-
-htmldoc: $(pngfiles) $(htmlfiles) $(DIRS)
-	@true
-
-pdfdoc: $(pngfiles) $(pdffiles) $(DIRS)
-	@true
-
-doxydoc: $(pdfimgfiles) $(DIRS)
-	@true
-
-.PHONY: $(DIRS)
-$(DIRS):
-	@[ -d $(CURDIR)/$@ ] || mkdir -p $(CURDIR)/$@
-	$(Q)$(MAKE) DOCDIR=$(DOCDIR)/$@ BASEDOCDIR=$(BASEDOCDIR)/.. \
-		-f $(RTE_SDK)/doc/$(DOCDIR)/$@/Makefile -C $(CURDIR)/$@ $(MAKECMDGOALS)
-
-%.png: %.svg
-	@echo "  INKSCAPE $(@)"
-	$(Q)inkscape -d $(DEFAULT_DPI) -D -b ffffff -y 1.0 -e $(call winpath,$(@)) $(call winpath,$(<))
-
-%.pdf: %.svg
-	@echo "  INKSCAPE $(@)"
-	$(Q)inkscape -d $(DEFAULT_DPI) -D -b ffffff -y 1.0 -A $(call winpath,$(@)) $(call winpath,$(<))
-
-.SECONDEXPANSION:
-$(foreach f,$(RST),$(eval DEP_$(f:%.rst=%.html) = $(DEP_$(f))))
-%.html: %.rst $$(DEP_$$@)
-	@echo "  RST2HTML $(@)"
-	$(Q)mkdir -p `dirname $(@)` ; \
-	python $(BASEDOCDIR)/gen/gen-common.py html $(BASEDOCDIR) > $(BASEDOCDIR)/gen/rte.rst ; \
-	python $(BASEDOCDIR)/html/rst2html-highlight.py --link-stylesheet \
-		--stylesheet-path=$(BASEDOCDIR)/html/rte.css \
-		--strip-comments< $(<) > $(@) ; \
-
-# there is a bug in rst2pdf (issue 311): replacement of DSTDIR is not
-# what we expect: we should not have to add doc/
-ifdef COMSPEC
-WORKAROUND_PATH=$(BASEDOCDIR)
-else
-WORKAROUND_PATH=$(BASEDOCDIR)/doc
-endif
-
-.SECONDEXPANSION:
-$(foreach f,$(RST),$(eval DEP_$(f:%.rst=%.pdf) = $(DEP_$(f))))
-%.pdf: %.rst $$(DEP_$$@)
-	@echo "  RST2PDF $(@)"
-	$(Q)mkdir -p `dirname $(@)` ; \
-	python $(BASEDOCDIR)/gen/gen-common.py pdf $(BASEDOCDIR) > $(BASEDOCDIR)/gen/rte.rst ; \
-	rst2pdf -s $(BASEDOCDIR)/pdf/rte-stylesheet.json \
-		--default-dpi=300 < $(<) > $(@)
-
-CLEANDIRS = $(addsuffix _clean,$(DIRS))
-
-docclean clean: $(CLEANDIRS)
-	@rm -f $(htmlfiles) $(pdffiles) $(pngfiles) $(pdfimgfiles) $(BASEDOCDIR)/gen/rte.rst
-
-%_clean:
-	@if [ -f $(RTE_SDK)/doc/$(DOCDIR)/$*/Makefile -a -d $(CURDIR)/$* ]; then \
-		$(MAKE) DOCDIR=$(DOCDIR)/$* BASEDOCDIR=$(BASEDOCDIR)/.. \
-		-f $(RTE_SDK)/doc/$(DOCDIR)/$*/Makefile -C $(CURDIR)/$* clean ; \
-	fi
-
-.NOTPARALLEL:
mk/rte.sdkdoc.mk +2 -31
index 8d7a296..57eb8e6 100644
@@ -31,12 +31,6 @@
 # 
 #  version: DPDK.L.1.2.3-3
 
-ifdef O
-ifeq ("$(origin O)", "command line")
-$(error "Cannot use O= with doc target")
-endif
-endif
-
 ifdef T
 ifeq ("$(origin T)", "command line")
 $(error "Cannot use T= with doc target")
@@ -45,29 +39,6 @@ endif
 
 .PHONY: doc
 doc:
-	$(Q)$(MAKE) -C $(RTE_SDK)/doc/images $@ BASEDOCDIR=.. DOCDIR=images
-	$(Q)$(MAKE) -f $(RTE_SDK)/doc/rst/Makefile -C $(RTE_SDK)/doc/pdf pdfdoc BASEDOCDIR=.. DOCDIR=rst
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk doxydoc
-
-.PHONY: pdfdoc
-pdfdoc:
-	$(Q)$(MAKE) -C $(RTE_SDK)/doc/images $@ BASEDOCDIR=.. DOCDIR=images
-	$(Q)$(MAKE) -f $(RTE_SDK)/doc/rst/Makefile -C $(RTE_SDK)/doc/pdf $@ BASEDOCDIR=.. DOCDIR=rst
-
-.PHONY: doxydoc
-doxydoc:
-	$(Q)$(MAKE) -C $(RTE_SDK)/doc/images $@ BASEDOCDIR=.. DOCDIR=images
-	$(Q)mkdir -p $(RTE_SDK)/doc/latex
-	$(Q)mkdir -p $(RTE_SDK)/doc/pdf/api
-	$(Q)cat $(RTE_SDK)/doc/gen/doxygen_pdf/Doxyfile | doxygen -
-	$(Q)mv $(RTE_SDK)/doc/images/*.pdf $(RTE_SDK)/doc/latex/
-	$(Q)sed -i s/darkgray/headercolour/g $(RTE_SDK)/doc/latex/doxygen.sty
-	$(Q)cp $(RTE_SDK)/doc/gen/doxygen_pdf/Makefile_doxygen $(RTE_SDK)/doc/latex/Makefile
-	$(Q)$(MAKE) -C $(RTE_SDK)/doc/latex
-	$(Q)cp $(RTE_SDK)/doc/latex/refman.pdf $(RTE_SDK)/doc/pdf/api/api.pdf
 
-.PHONY: docclean
-docclean:
-	$(Q)$(MAKE) -C $(RTE_SDK)/doc/images $@ BASEDOCDIR=.. DOCDIR=images
-	$(Q)$(MAKE) -f $(RTE_SDK)/doc/rst/Makefile -C $(RTE_SDK)/doc/pdf $@ BASEDOCDIR=.. DOCDIR=rst
-	$(Q)rm -rf $(RTE_SDK)/doc/pdf/api $(RTE_SDK)/doc/latex
+.PHONY: doc-clean
+doc-clean:
mk/rte.sdkroot.mk +2 -7
index 6221bec..fe0070e 100644
@@ -103,8 +103,8 @@ testall testimport:
 install uninstall:
 	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkinstall.mk $@
 
-.PHONY: doc pdfdoc doxydoc docclean
-doc pdfdoc doxydoc docclean:
+.PHONY: doc doc-clean
+doc doc-clean:
 	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk $@
 
 .PHONY: depdirs depgraph
@@ -115,11 +115,6 @@ depdirs depgraph:
 gcov gcovclean:
 	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkgcov.mk $@
 
-.PHONY: help
-help:
-	@sed -e '1,/.*==================================.*/ d' \
-		doc/rst/developers_reference/sdk_mkhelp.rst
-
 # all other build targets
 %:
 	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkconfig.mk checkconfig
Signature · 1 line
1.7.10.4
#5 lore raw

PATCH 4/4 doc: generate HTML for API with doxygen

In reply to a message not in the archive

- add index page
- add doxygen configuration for API
- add doxygen CSS customization applied by a script
- HTML generation via make rules

The configuration is splitted in a static file and a make rule in order to dynamically configure output format and path.

---
 doc/doxy-api-index.md   |  101 +++++++++++++++++++++++++++++++++++++++++++++++
 doc/doxy-api.conf       |   59 +++++++++++++++++++++++++++
 doc/doxy-html-custom.sh |    6 +++
 mk/rte.sdkdoc.mk        |   27 +++++++++++--
 mk/rte.sdkroot.mk       |    7 ++--
 5 files changed, 193 insertions(+), 7 deletions(-)
 create mode 100644 doc/doxy-api-index.md
 create mode 100644 doc/doxy-api.conf
 create mode 100755 doc/doxy-html-custom.sh
doc/doxy-api-index.md new file +101 -0
new file mode 100644
index 0000000..de872ec
@@ -0,0 +1,101 @@
+<!--
+  BSD LICENSE
+
+  Copyright(c) 2013 6WIND.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions
+  are met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in
+      the documentation and/or other materials provided with the
+      distribution.
+    * Neither the name of 6WIND S.A. nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+-->
+
+# API {#index}
+
+There are many libraries, so their headers may be grouped by topics:
+
+- **device**:
+  [ethdev]             (@ref rte_ethdev.h),
+  [PCI]                (@ref rte_pci.h),
+  [PCI IDs]            (@ref rte_pci_dev_ids.h)
+
+- **memory**:
+  [memseg]             (@ref rte_memory.h),
+  [memzone]            (@ref rte_memzone.h),
+  [mempool]            (@ref rte_mempool.h),
+  [malloc]             (@ref rte_malloc.h),
+  [memcpy]             (@ref rte_memcpy.h)
+
+- **timers**:
+  [cycles]             (@ref rte_cycles.h),
+  [timer]              (@ref rte_timer.h),
+  [alarm]              (@ref rte_alarm.h)
+
+- **locks**:
+  [atomic]             (@ref rte_atomic.h),
+  [rwlock]             (@ref rte_rwlock.h),
+  [spinlock]           (@ref rte_spinlock.h)
+
+- **cpu arch**:
+  [branch prediction]  (@ref rte_branch_prediction.h),
+  [cache prefetch]     (@ref rte_prefetch.h),
+  [byte order]         (@ref rte_byteorder.h),
+  [CPU flags]          (@ref rte_cpuflags.h)
+
+- **cpu multicore**:
+  [interrupts]         (@ref rte_interrupts.h),
+  [launch]             (@ref rte_launch.h),
+  [lcore]              (@ref rte_lcore.h),
+  [per-lcore]          (@ref rte_per_lcore.h)
+
+- **network stack**:
+  [ethernet]           (@ref rte_ether.h),
+  [IP]                 (@ref rte_ip.h),
+  [SCTP]               (@ref rte_sctp.h),
+  [TCP]                (@ref rte_tcp.h),
+  [UDP]                (@ref rte_udp.h),
+  [LPM route]          (@ref rte_lpm.h)
+
+- **hashes**:
+  [hash]               (@ref rte_hash.h),
+  [jhash]              (@ref rte_jhash.h),
+  [FBK hash]           (@ref rte_fbk_hash.h),
+  [CRC hash]           (@ref rte_hash_crc.h)
+
+- **containers**:
+  [mbuf]               (@ref rte_mbuf.h),
+  [ring]               (@ref rte_ring.h),
+  [tailq]              (@ref rte_tailq.h)
+
+- **debug**:
+  [debug]              (@ref rte_debug.h),
+  [log]                (@ref rte_log.h),
+  [warnings]           (@ref rte_warnings.h),
+  [errno]              (@ref rte_errno.h)
+
+- **misc**:
+  [EAL config]         (@ref rte_eal.h),
+  [common]             (@ref rte_common.h),
+  [random]             (@ref rte_random.h),
+  [string]             (@ref rte_string_fns.h),
+  [version]            (@ref rte_version.h)
doc/doxy-api.conf new file +59 -0

59 lines not on this page · raw message

doc/doxy-html-custom.sh new file +6 -0
new file mode 100755
index 0000000..2465cc2
@@ -0,0 +1,6 @@
+#! /bin/sh -e
+
+CSS=$1
+
+# space between item and its comment
+echo 'dd td:first-child {padding-right: 2em;}' >> $CSS
mk/rte.sdkdoc.mk +23 -4
index 57eb8e6..edae1e7 100644
@@ -1,6 +1,7 @@
 #   BSD LICENSE
 # 
 #   Copyright(c) 2010-2012 Intel Corporation. All rights reserved.
+#   Copyright(c) 2013 6WIND.
 #   All rights reserved.
 # 
 #   Redistribution and use in source and binary forms, with or without 
@@ -37,8 +38,26 @@ $(error "Cannot use T= with doc target")
 endif
 endif
 
-.PHONY: doc
-doc:
+.PHONY: all
+all: htmlapi
 
-.PHONY: doc-clean
-doc-clean:
+.PHONY: clean
+clean: htmlapi-clean
+
+.PHONY: htmlapi
+htmlapi: htmlapi-clean
+	@echo 'doxygen for API...'
+	$(Q)mkdir -p $(RTE_OUTPUT)/doc/html
+	$(Q)(cat $(RTE_SDK)/doc/doxy-api.conf         && \
+	    echo OUTPUT_DIRECTORY = $(RTE_OUTPUT)/doc && \
+	    echo HTML_OUTPUT      = html/api          && \
+	    echo GENERATE_HTML    = YES               && \
+	    echo GENERATE_LATEX   = NO                && \
+	    echo GENERATE_MAN     = NO                )| \
+	    doxygen -
+	$(Q)$(RTE_SDK)/doc/doxy-html-custom.sh $(RTE_OUTPUT)/doc/html/api/doxygen.css
+
+.PHONY: htmlapi-clean
+htmlapi-clean:
+	$(Q)rm -f $O/doc/html/api/*
+	$(Q)rmdir -p --ignore-fail-on-non-empty $(RTE_OUTPUT)/doc/html/api 2>&- || true
mk/rte.sdkroot.mk +4 -3
index fe0070e..f555e33 100644
@@ -103,9 +103,10 @@ testall testimport:
 install uninstall:
 	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkinstall.mk $@
 
-.PHONY: doc doc-clean
-doc doc-clean:
-	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk $@
+.PHONY: doc
+doc: doc-all
+doc-%:
+	$(Q)$(MAKE) -f $(RTE_SDK)/mk/rte.sdkdoc.mk $*
 
 .PHONY: depdirs depgraph
 depdirs depgraph:
Signature · 1 line
1.7.10.4
#6 lore raw
In reply to a message not in the archive

Hi Thomas,

Sorry for the late answer. The patches look good to me. By the way it would be great to add a working "make help" in a future commit.

Regards,
Olivier

Quoted 27 lines · Thomas Monjalon

These patches aims to generate a documentation for API from doxygen.

Thomas Monjalon (4):
lib: fix some doxygen comments
mk: factorize some rules
mk: clean dead doc rules
doc: generate HTML for API with doxygen

 doc/doxy-api-index.md                          |  101 +++++++++++++++++++
 doc/doxy-api.conf                              |   59 +++++++++++
 doc/doxy-html-custom.sh                        |    6 ++
 lib/librte_eal/common/include/rte_debug.h      |    2 +-
 lib/librte_eal/common/include/rte_pci.h        |    4 +-
 lib/librte_eal/common/include/rte_string_fns.h |    4 +-
 lib/librte_ether/rte_ethdev.h                  |    6 +-
 mk/rte.doc.mk                                  |  127 ------------------------
 mk/rte.sdkdoc.mk                               |   52 ++++------
 mk/rte.sdkroot.mk                              |   72 ++++----------
 10 files changed, 213 insertions(+), 220 deletions(-)
 create mode 100644 doc/doxy-api-index.md
 create mode 100644 doc/doxy-api.conf
 create mode 100755 doc/doxy-html-custom.sh
 delete mode 100644 mk/rte.doc.mk

_______________________________________________
dev mailing list
[email protected]
http://dpdk.org/ml/listinfo/dev

A message that is not in the archive (sent off-list or not yet received): [email protected]

#8 lore raw

24/04/2013 15:40, Olivier MATZ :

Quoted 2 lines

Sorry for the late answer. The patches look good to me. By the way it would be great to add a working "make help" in a future commit.

OK thanks for your review.
I've pushed these patches with a little modification in doxy-api-index.md: title has moved before header and syntax is fixed to have it on main page.

I'll submit a "make help" soon.

Signature · 1 line
Thomas