From fec10a282355def49133e63b8a4591cc51b46478 Mon Sep 17 00:00:00 2001 From: Thomas Graf Date: Thu, 10 May 2012 12:03:59 +0200 Subject: doc: documentation restructuring - changes the modules hierarchy to better represent the set of libaries - list the header file that needs to be included - remove examples/doc from api ref that is included in the guide - add references to the guide - fix doxygen api linking for version 1.8.0 - readd doxygen mainpage to config file - fix a couple of doxygen doc bugs --- doc/Doxyfile.in | 13 +++++++------ doc/Makefile.am | 21 +++++++++------------ doc/README | 4 ++-- doc/api/.gitignore | 1 + doc/core.txt | 11 +++++++++++ doc/gen-tags.sh | 10 ++-------- doc/src/toc.c | 17 +++++------------ doc/tags2dict.sh | 8 -------- 8 files changed, 37 insertions(+), 48 deletions(-) delete mode 100755 doc/tags2dict.sh (limited to 'doc') diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 8bb4fd5d..d515db21 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -181,11 +181,11 @@ TAB_SIZE = 8 ALIASES = arg=\param -ALIASES += ref_asciidoc{3}="\3" -ALIASES += ref_core{2}="\ref_asciidoc{core,\1,\2 (Netlink Library)}" -ALIASES += ref_route{2}="\ref_asciidoc{route,\1,\2 (Routing Family Library)}" -ALIASES += core_doc{2}="\par Related Documentation:\n\ref_core{\1,\2}" -ALIASES += route_doc{2}="\par Related Documentation:\n\ref_route{\1,\2}" +ALIASES += ref_asciidoc{3}="\3" +ALIASES += ref_core{2}="\ref_asciidoc{core,\1,\2 (Netlink Core Library Development Guide)}" +ALIASES += ref_route{2}="\ref_asciidoc{route,\1,\2 (Netlink Routing Development Guide)}" +ALIASES += core_doc{2}="\ref_core{\1,\2}" +ALIASES += route_doc{2}="\ref_route{\1,\2}" # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C # sources only. Doxygen will then generate output that is more tailored for C. @@ -590,7 +590,8 @@ WARN_LOGFILE = INPUT = @top_srcdir@/lib \ @top_srcdir@/src/lib \ @top_srcdir@/include/netlink \ - @top_srcdir@/src + @top_srcdir@/src \ + @top_srcdir@/doc/src # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is diff --git a/doc/Makefile.am b/doc/Makefile.am index 142dc31b..ffa22459 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -20,7 +20,6 @@ EXTRA_DIST = \ doxygen-link.py \ gen-tags.sh \ resolve-asciidoc-refs.py \ - tags2dict.sh \ stylesheets/asciidoc.css \ stylesheets/asciidoc-manpage.css \ stylesheets/docbook-xsl.css \ @@ -78,28 +77,26 @@ EXTRA_DIST = \ images/icons/callouts/14.png \ images/icons/callouts/15.png -%.html: %.txt +link_doc: if LINK_DOC + ./gen-tags.sh > libnl.dict +else + @echo "Warning: Linking to API reference is disabled, check configure output" +endif + + +%.html: %.txt link_doc ./resolve-asciidoc-refs.py $< > asciidoc.tmp asciidoc $(ASCIIDOCOPTS) -o $@ asciidoc.tmp +if LINK_DOC ./doxygen-link.py libnl.dict $@ > asciidoc.tmp mv asciidoc.tmp $@ -else - asciidoc $(ASCIIDOCOPTS) -o $@ $< endif asciidoc: core.html route.html index.html -link_doc: -if LINK_DOC - ./gen-tags.sh | ./tags2dict.sh > libnl.dict -else - @echo "Warning: Linking to API reference is disabled, check configure output" -endif - api_ref: doxygen Doxyfile; - $(MAKE) link_doc gendoc: if GENERATE_DOC diff --git a/doc/README b/doc/README index 0c230a2c..0784e13b 100644 --- a/doc/README +++ b/doc/README @@ -6,5 +6,5 @@ mscgen mscgen-filter-1.2 http://code.google.com/p/asciidoc-mscgen-filter/ -asciidoc 8.6.x -doxygen +asciidoc > 8.6.x +doxygen > 1.8.0 diff --git a/doc/api/.gitignore b/doc/api/.gitignore index 821cf658..e57ca889 100644 --- a/doc/api/.gitignore +++ b/doc/api/.gitignore @@ -3,5 +3,6 @@ *.css *.map *.md5 +*.js formula.repository jquery.js diff --git a/doc/core.txt b/doc/core.txt index 7f26e051..8a26dbad 100644 --- a/doc/core.txt +++ b/doc/core.txt @@ -2811,6 +2811,17 @@ is stored in +*result+. NOTE: Make sure to return the reference to an address using `nl_addr_put()` after usage to allow memory being freed. +.Example: Transform character string to abstract address +[source,c] +----- +struct nl_addr *a = nl_addr_parse("::1", AF_UNSPEC); +printf("Address family: %s\n", nl_af2str(nl_addr_get_family(a))); +nl_addr_put(a); +a = nl_addr_parse("11:22:33:44:55:66", AF_UNSPEC); +printf("Address family: %s\n", nl_af2str(nl_addr_get_family(a))); +nl_addr_put(a); +----- + .Address References Abstract addresses use reference counting to account for all users of diff --git a/doc/gen-tags.sh b/doc/gen-tags.sh index aba66720..862ec090 100755 --- a/doc/gen-tags.sh +++ b/doc/gen-tags.sh @@ -5,16 +5,10 @@ # written by Carsten Haitzler # -echo '' for f in api/group__*.html do bf=$(basename $f) - grep -oE '' $f | - sed 's//file=\"$bf\" \/>/" | - sed "s/ ref=\"/ href=\"$bf#/" | - sed 's/ member="\([^:]*::\)\([^"]*\)"/ member="\2"/' | - sed 's/ member="\([^"]*\)"/ short="\1"/' + grep -oE "href=\"$bf#[a-z0-9]+\">[^<]+" $f | + sed 's/href="\([^"]*\)">\([^<]*\)<\/a>/\2=api\/\1/' done -echo '' diff --git a/doc/src/toc.c b/doc/src/toc.c index ba7e07a4..570c1dfe 100644 --- a/doc/src/toc.c +++ b/doc/src/toc.c @@ -9,11 +9,11 @@ libnl is a set of libraries to deal with the netlink protocol and some of the high level protocols implemented on top of it. The goal is to -provide APIs on different levels of abstraction. The core library libnl.so +provide APIs on different levels of abstraction. The core library libnl provides a fundamental set of functions to deal with sockets, construct messages, and send/receive those messages. Additional high level interfaces for several individual netlink protocols are provided in separate -libraries (e.g. "nl-route.so", "nl-genl.so", ...). +libraries (e.g. "nl-route", "nl-genl", ...). The library is designed to ensure that all components are optional, i.e. even though the core library provides a caching system which allows to @@ -33,16 +33,9 @@ version is used with a considerably older kernel. \subsection tree_dev Development Tree @code -git://git.kernel.org/pub/scm/libs/netlink/libnl.git +git://git.infradead.org/users/tgr/libnl.git @endcode -- Web: http://www.kernel.org/pub/scm/libs/netlink/libnl.git - -\subsection tree_stable Stable Tree - -@code -git://git.kernel.org/pub/scm/libs/netlink/libnl-stable.git -@endcode -- Web: http://www.kernel.org/pub/scm/libs/netlink/libnl-stable.git +- Web: http://git.infradead.org/users/tgr/libnl.git \section main_website Website @@ -50,7 +43,7 @@ git://git.kernel.org/pub/scm/libs/netlink/libnl-stable.git \section main_mailinglist Mailinglist -Please post question and patches to the libnl mailinglist: +Please post questions and patches to the libnl mailinglist: @code libnl@lists.infradead.org diff --git a/doc/tags2dict.sh b/doc/tags2dict.sh deleted file mode 100755 index 76407af2..00000000 --- a/doc/tags2dict.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/bin/bash -xmlstarlet sel -t \ - -m "/libnltags/libnltag[@href]" \ - -v "@short" \ - -o "=api/" \ - -v "@href" \ - -n - -- cgit v1.2.3