From 8238f628b91b01deec8270eda46d0fd0f712c999 Mon Sep 17 00:00:00 2001 From: Jon Shallow Date: Thu, 9 Aug 2018 21:14:38 +0100 Subject: [PATCH] Include man pages into Doxygen. Add landing page for Doxygen Added in a new landing page for Main Page doc/main.md (new) Enabled Tree View of whats available Disable Related Pages TAB as it fills up with the man pages - updated doc/Doxyfile.in Get a2x to also generate html man pages which are then included. These html files are updated to correct the lowercasing of NAME and SYNOPSIS. The SEE ALSO references to other man pages are made hyper links. - done by doc/build_man_files.sh (new) Created a new TAB Manual Pages Created a new TAB Depricated Items - done by modifing DoxygenLayout.xml file using doc/build_man_files.sh Updated .gitignore to ignore additional files and autogen.sh to clean them up man/coap*txt.in updated to display as expected in Doxygen. This only updates documentation .gitignore Makefile.am autogen.sh doc/Doxyfile.in doc/Makefile.am doc/build_man_files.sh (New) doc/main.md (New) include/coap/debug.h include/coap/encode.h include/coap/option.h include/coap/pdu.h include/coap/prng.h man/Makefile.am man/coap.txt.in man/coap_attribute.txt.in man/coap_context.txt.in man/coap_encryption.txt.in man/coap_handler.txt.in man/coap_logging.txt.in man/coap_observe.txt.in man/coap_pdu_setup.txt.in man/coap_recovery.txt.in man/coap_resource.txt.in man/coap_session.txt.in man/coap_tls_library.txt.in --- .gitignore | 6 +++ Makefile.am | 2 +- autogen.sh | 3 +- doc/Doxyfile.in | 12 ++--- doc/Makefile.am | 5 ++- doc/build_man_files.sh | 88 +++++++++++++++++++++++++++++++++++++ doc/main.md | 34 ++++++++++++++ include/coap/debug.h | 6 +-- include/coap/encode.h | 2 +- include/coap/option.h | 1 + include/coap/pdu.h | 2 +- include/coap/prng.h | 1 + man/Makefile.am | 5 ++- man/coap.txt.in | 6 ++- man/coap_attribute.txt.in | 2 +- man/coap_context.txt.in | 2 +- man/coap_encryption.txt.in | 2 +- man/coap_handler.txt.in | 2 +- man/coap_logging.txt.in | 2 +- man/coap_observe.txt.in | 2 +- man/coap_pdu_setup.txt.in | 2 +- man/coap_recovery.txt.in | 2 +- man/coap_resource.txt.in | 2 +- man/coap_session.txt.in | 4 +- man/coap_tls_library.txt.in | 4 +- 25 files changed, 171 insertions(+), 28 deletions(-) create mode 100755 doc/build_man_files.sh create mode 100644 doc/main.md diff --git a/.gitignore b/.gitignore index 070ce3a5..274e37aa 100644 --- a/.gitignore +++ b/.gitignore @@ -45,11 +45,16 @@ doc/Doxyfile doc/Makefile.in doc/doxyfile.stamp doc/doxygen_sqlite3.db +doc/DoxygenLayout.xml doc/html/ +doc/man_html/ +doc/man_tmp/ # the man/ folder +man/docbook-xsl.css man/Makefile man/Makefile.in +man/*.html man/*.txt man/*.xml man/*.3 @@ -68,6 +73,7 @@ include/coap/coap.h # the tests/ folder tests/.deps +tests/oss-fuzz/Makefile.ci tests/testdriver tests/*.o diff --git a/Makefile.am b/Makefile.am index 2ae82ca5..e735b7c0 100644 --- a/Makefile.am +++ b/Makefile.am @@ -47,7 +47,7 @@ EXTRA_DIST = \ AM_CFLAGS = -I$(top_builddir)/include/coap -I$(top_srcdir)/include/coap $(WARNING_CFLAGS) $(DTLS_CFLAGS) -std=c99 -SUBDIRS = $(subdirs) . $(DOC_DIR) $(MAN_DIR) tests examples +SUBDIRS = $(subdirs) . $(MAN_DIR) $(DOC_DIR) tests examples ## Define a libtool archive target "libcoap-@LIBCOAP_NAME_SUFFIX@.la", with ## @LIBCOAP_NAME_SUFFIX@ substituted into the generated Makefile at configure diff --git a/autogen.sh b/autogen.sh index 813729ce..fe12ea25 100755 --- a/autogen.sh +++ b/autogen.sh @@ -30,11 +30,12 @@ examples/Makefile examples/Makefile.in include/coap/coap.h install-sh libcoap-*.pc libtool ltmain.sh -man/coap_*.[357] man/coap_*.txt man/coap-*.txt man/Makefile man/Makefile.in +man/coap*.[357] man/coap*.txt man/Makefile man/Makefile.in missing Makefile Makefile.in stamp-h1 src/.dirstamp libcoap*.la* src/*.*o tests/*.o tests/Makefile tests/Makefile.in tests/testdriver +tests/oss-fuzz/Makefile.ci m4/libtool.m4 m4/lt~obsolete.m4 m4/ltoptions.m4 m4/ltsugar.m4 m4/ltversion.m4 " diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 76a69139..00bfcd93 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -753,8 +753,10 @@ WARN_LOGFILE = # spaces. # Note: If this tag is empty the current directory is searched. -INPUT = @top_srcdir@/src \ - @top_srcdir@/include/coap +INPUT = main.md \ + @top_srcdir@/src \ + @top_srcdir@/include/coap \ + man_tmp # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -823,7 +825,7 @@ EXCLUDE_SYMBOLS = # that contain example code fragments that are included (see the \include # command). -EXAMPLE_PATH = +EXAMPLE_PATH = man_html # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and @@ -1157,7 +1159,7 @@ HTML_TIMESTAMP = YES # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -HTML_DYNAMIC_SECTIONS = NO +HTML_DYNAMIC_SECTIONS = YES # With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries # shown in the various tree structured indices initially; the user can expand @@ -1386,7 +1388,7 @@ DISABLE_INDEX = NO # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -GENERATE_TREEVIEW = NO +GENERATE_TREEVIEW = YES # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that # doxygen will group on one line in the generated HTML documentation. diff --git a/doc/Makefile.am b/doc/Makefile.am index 27cb237a..c12cebc6 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -32,10 +32,13 @@ uninstall-am: -rm -rf $(DESTDIR)$(htmldir)/html all: +if BUILD_MANPAGES + @./build_man_files.sh +endif # BUILD_MANPAGES $(DOXYGEN) Doxyfile clean-local: - rm -rf $(top_builddir)/doc/html + -rm -rf $(top_builddir)/doc/html man_tmp man_html DoxygenLayout.xml distclean-local: clean-local diff --git a/doc/build_man_files.sh b/doc/build_man_files.sh new file mode 100755 index 00000000..1db7309e --- /dev/null +++ b/doc/build_man_files.sh @@ -0,0 +1,88 @@ +#!/bin/sh + +# +# general initialization cleanup +# +rm -f DoxygenLayout.xml +rm -rf man_tmp +mkdir -p man_tmp +rm -rf man_html +mkdir -p man_html + +# +# Prefix the start of the 2 files +# +echo ' ' > insert_file +echo '/** @page manpage Manual Pages' > man_tmp/manpage.dox +echo ' Here is a list of libcoap API manual pages, some of which have code examples:' >> man_tmp/manpage.dox +echo ' ' >> man_tmp/manpage.dox + +FILES=`( cd ../man ; ls coap.txt.in ; ls coap_*.txt.in ; ls coap-*.txt.in )` +ID=0 +ROW_EVEN=" class=\"even\"" + +for FILE in $FILES ; do + BASE=`echo $FILE | cut -d. -f 1` + MANUAL=`cat ../man/$FILE | egrep -B 1 "^====" | head -1` + SUMMARY=`cat ../man/$FILE | egrep -B 2 "^SYNOPSIS" | sed 's/coap-//g' | cut -d\- -f2 | cut -c2- | head -1` + + # + # Build the manual insert page + # + echo "/// @page man_$BASE $MANUAL" > man_tmp/$MANUAL.dox + echo "/// @htmlinclude $BASE.html $MANUAL" >> man_tmp/$MANUAL.dox + + # + # Update insert_file + # + echo " " >> insert_file + + # + # Update the summary man page + # + echo " " >> man_tmp/manpage.dox + echo " " >> man_tmp/manpage.dox + echo " " >> man_tmp/manpage.dox + ID=`expr $ID + 1` + if [ -z $ROW_EVEN ] ; then + ROW_EVEN=" class=\"even\"" + else + ROW_EVEN= + fi +done + +# +# Close off the man page file +# +echo '
@ref man_$BASE $MANUAL - $SUMMARY
' >> man_tmp/manpage.dox +echo ' */' >> man_tmp/manpage.dox + +# +# Close off the insert_file +# +echo ' ' >> insert_file +echo ' ' >> insert_file + +# +# Create and Update the DoxygenLayout.xml file +# +doxygen -l +sed -i 's/Name^

NAME

^g' | sed 's^

Synopsis

^

SYNOPSIS

^g' > man_html/$BASE.html + + for ENTRY in $FILES ; do + EBASE=`echo $ENTRY | cut -d. -f 1` + MANUAL=`cat ../man/$ENTRY | egrep -B 1 "^====" | head -1` + SECTION=`echo $MANUAL | cut -d\( -f2 | cut -d\) -f1` + + sed -i "s^$EBASE($SECTION)^$EBASE($SECTION)^g" man_html/$BASE.html + done +done diff --git a/doc/main.md b/doc/main.md new file mode 100644 index 00000000..11b7efd1 --- /dev/null +++ b/doc/main.md @@ -0,0 +1,34 @@ +libcoap {#mainpage} +======= + +A C implementation of the Constrained Application Protocol (RFC 7252) +===================================================================== + +Copyright (C) 2010--2018 by Olaf Bergmann and others + +About libcoap +============= + +libcoap is a C implementation of a lightweight application-protocol +for devices that are constrained their resources such as computing +power, RF range, memory, bandwith, or network packet sizes. This +protocol, CoAP, is standardized by the IETF as RFC 7252. For further +information related to CoAP, see . + +You might want to check out +[libcoap-minimal](https://github.com/obgm/libcoap-minimal) for usage +examples. + +Documentation +============= + +This set of pages contains the current set of documention for the libcoap APIs. + +Licence Information +=================== + +This library is published as open-source software without any warranty +of any kind. Use is permitted under the terms of the simplified BSD +license. It includes public domain software. libcoap binaries may also +include open-source software with their respective licensing terms. +Please refer to LICENSE for further details in the source. diff --git a/include/coap/debug.h b/include/coap/debug.h index 3820875f..a40da8e1 100644 --- a/include/coap/debug.h +++ b/include/coap/debug.h @@ -128,17 +128,17 @@ void coap_log_impl(coap_log_t level, const char *format, ...); /* A set of convenience macros for common log levels. */ /** * Obsoleted. - * @deprecated Use coap_log(LOG_INFO, ...). + * @deprecated Use coap_log(LOG_INFO, ...) instead. */ #define info(...) coap_log(LOG_INFO, __VA_ARGS__) /** * Obsoleted. - * @deprecated Use coap_log(LOG_WARNING, ...). + * @deprecated Use coap_log(LOG_WARNING, ...) instead. */ #define warn(...) coap_log(LOG_WARNING, __VA_ARGS__) /** * Obsoleted. - * @deprecated Use coap_log(LOG_DEBUG, ...). + * @deprecated Use coap_log(LOG_DEBUG, ...) instead. */ #define debug(...) coap_log(LOG_DEBUG, __VA_ARGS__) diff --git a/include/coap/encode.h b/include/coap/encode.h index 04a3b742..2697357b 100644 --- a/include/coap/encode.h +++ b/include/coap/encode.h @@ -73,7 +73,7 @@ unsigned int coap_encode_var_safe(uint8_t *buf, unsigned int value); /** - * @deprecated. Use coap_encode_var_safe() instead. + * @deprecated Use coap_encode_var_safe() instead. * Provided for backward compatability. As @p value has a * maximum value of 0xffffffff, and buf is usually defined as an array, it * is unsafe to continue to use this variant if buf[] is less than buf[4]. diff --git a/include/coap/option.h b/include/coap/option.h index 1b6bd738..5cec4f50 100644 --- a/include/coap/option.h +++ b/include/coap/option.h @@ -63,6 +63,7 @@ size_t coap_opt_size(const coap_opt_t *opt); /** * @defgroup opt_filter Option Filters + * API functions for access option filters * @{ */ diff --git a/include/coap/pdu.h b/include/coap/pdu.h index cbdbe157..a581abb5 100644 --- a/include/coap/pdu.h +++ b/include/coap/pdu.h @@ -254,7 +254,7 @@ typedef int coap_tid_t; #define COAP_PAYLOAD_START 0xFF /* payload marker */ /** - * @deprecated. Use coap_optlist_t instead. + * @deprecated Use coap_optlist_t instead. * * Structures for more convenient handling of options. (To be used with ordered * coap_list_t.) The option's data will be added to the end of the coap_option diff --git a/include/coap/prng.h b/include/coap/prng.h index 4daed54d..3cc73c8f 100644 --- a/include/coap/prng.h +++ b/include/coap/prng.h @@ -17,6 +17,7 @@ /** * @defgroup prng Pseudo Random Numbers + * API functions for gerating pseudo random numbers * @{ */ diff --git a/man/Makefile.am b/man/Makefile.am index 426d9490..4c3e438f 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -42,12 +42,15 @@ man7_MANS = $(MAN7) .txt.3: $(A2X) --doctype manpage --format manpage $< + $(A2X) --doctype manpage --format xhtml $< .txt.5: $(A2X) --doctype manpage --format manpage $< + $(A2X) --doctype manpage --format xhtml $< .txt.7: $(A2X) --doctype manpage --format manpage $< + $(A2X) --doctype manpage --format xhtml $< # We are limited to 10 names, but synopsis can cover more install-man: install-man3 install-man5 install-man7 @@ -61,6 +64,6 @@ install-man: install-man3 install-man5 install-man7 @echo ".so man3/coap_logging.3" > coap_session_str.3 $(INSTALL_DATA) *.3 "$(DESTDIR)$(man3dir)" -CLEANFILES = *.3 *.5 *.7 *.xml +CLEANFILES = *.3 *.5 *.7 *.xml *.html docbook-xsl.css endif # BUILD_MANPAGES diff --git a/man/coap.txt.in b/man/coap.txt.in index 2a197803..ed74a55a 100644 --- a/man/coap.txt.in +++ b/man/coap.txt.in @@ -10,7 +10,11 @@ coap(7) NAME ---- -coap - overview of the libcoap library +coap - Overview of the libcoap library + +SYNOPSIS +-------- +Summary of the different libcoap API manual pages. DESCRIPTION ----------- diff --git a/man/coap_attribute.txt.in b/man/coap_attribute.txt.in index 06f06cb8..e2dced00 100644 --- a/man/coap_attribute.txt.in +++ b/man/coap_attribute.txt.in @@ -11,7 +11,7 @@ coap_attribute(3) NAME ---- coap_attribute, coap_add_attr, coap_find_attr -- work with CoAP attributes +- Work with CoAP attributes SYNOPSIS -------- diff --git a/man/coap_context.txt.in b/man/coap_context.txt.in index 3154e487..6dd1f89c 100644 --- a/man/coap_context.txt.in +++ b/man/coap_context.txt.in @@ -13,7 +13,7 @@ NAME coap_context, coap_new_context, coap_free_context, coap_context_set_pki, coap_context_set_psk, coap_new_endpoint, coap_free_endpoint, coap_endpoint_set_default_mtu, coap_endpoint_str -- work with CoAP contexts +- Work with CoAP contexts SYNOPSIS -------- diff --git a/man/coap_encryption.txt.in b/man/coap_encryption.txt.in index c83ea92b..e715d556 100644 --- a/man/coap_encryption.txt.in +++ b/man/coap_encryption.txt.in @@ -11,7 +11,7 @@ coap_encryption(3) NAME ---- coap_encryption, coap_dtls_pki_t -- work with CoAP tls/dtls +- Work with CoAP tls/dtls SYNOPSIS -------- diff --git a/man/coap_handler.txt.in b/man/coap_handler.txt.in index 12f5f8a4..2b945631 100644 --- a/man/coap_handler.txt.in +++ b/man/coap_handler.txt.in @@ -12,7 +12,7 @@ NAME ---- coap_handler, coap_register_handler, coap_register_response_handler, coap_register_nack_handler, coap_register_ping_handler, -coap_register_pong_handler, coap_register_event_handler +ccoap_register_pong_handler, coap_register_event_handler - work with CoAP handlers SYNOPSIS diff --git a/man/coap_logging.txt.in b/man/coap_logging.txt.in index b2f0fb67..29be48c8 100644 --- a/man/coap_logging.txt.in +++ b/man/coap_logging.txt.in @@ -13,7 +13,7 @@ NAME coap_logging, coap_log, coap_get_log_level, coap_set_log_level, coap_set_log_handler, coap_package_name, coap_package_version, coap_set_show_pdu_output, coap_show_pdu -- work with CoAP logging +- Work with CoAP logging SYNOPSIS -------- diff --git a/man/coap_observe.txt.in b/man/coap_observe.txt.in index 70960b80..638fc770 100644 --- a/man/coap_observe.txt.in +++ b/man/coap_observe.txt.in @@ -11,7 +11,7 @@ coap_observe(3) NAME ---- coap_observe, coap_resource_set_get_observable, coap_resource_notify_observers, -coap_resource_get_uri_path, coap_find_observer - work with CoAP observe +coap_resource_get_uri_path, coap_find_observer - Work with CoAP observe SYNOPSIS -------- diff --git a/man/coap_pdu_setup.txt.in b/man/coap_pdu_setup.txt.in index 0df70f09..19749c81 100644 --- a/man/coap_pdu_setup.txt.in +++ b/man/coap_pdu_setup.txt.in @@ -12,7 +12,7 @@ NAME ---- coap_pdu_setup, coap_pdu_init, coap_add_token, coap_new_optlist, coap_insert_optlist, coap_delete_optlist, coap_add_optlist_pdu, -coap_add_option, coap_add_data - work with CoAP PDUs +coap_add_option, coap_add_data - Work with CoAP PDUs SYNOPSIS -------- diff --git a/man/coap_recovery.txt.in b/man/coap_recovery.txt.in index 7116a73c..fd0e0685 100644 --- a/man/coap_recovery.txt.in +++ b/man/coap_recovery.txt.in @@ -14,7 +14,7 @@ coap_recovery, coap_session_set_max_retransmit, coap_session_set_ack_timeout, coap_session_set_ack_random_factor, coap_session_get_max_transmit, coap_session_get_ack_timeout, coap_session_get_ack_random_factor, coap_debug_set_packet_loss -- work with CoAP packet transmissions +- Work with CoAP packet transmissions SYNOPSIS -------- diff --git a/man/coap_resource.txt.in b/man/coap_resource.txt.in index 3757365a..6eca5820 100644 --- a/man/coap_resource.txt.in +++ b/man/coap_resource.txt.in @@ -12,7 +12,7 @@ NAME ---- coap_resource, coap_resource_init, coap_resource_unknown_init, coap_add_resource, coap_delete_resource, coap_delete_all_resources, -coap_resource_set_mode - work with CoAP resources +coap_resource_set_mode - Work with CoAP resources SYNOPSIS -------- diff --git a/man/coap_session.txt.in b/man/coap_session.txt.in index a80108be..56b8de9a 100644 --- a/man/coap_session.txt.in +++ b/man/coap_session.txt.in @@ -18,7 +18,7 @@ coap_session_reference, coap_session_release, coap_session_set_mtu, coap_session_max_pdu_size, -coap_session_str - work with CoAP sessions +coap_session_str - Work with CoAP sessions SYNOPSIS -------- @@ -131,7 +131,7 @@ address or port. The session will initially have a reference count of 1. The *coap_new_client_session_pki*() function, for a specific _context_, is used to configure the TLS context using the _setup_data_ variables as defined -in the coap_dtls_pki_t structure - see *coap_encrytion(*3). +in the coap_dtls_pki_t structure - see *coap_encrytion*(3). The session will initially have a reference count of 1. The *coap_new_client_session_psk*() function, for a specific _context_, is diff --git a/man/coap_tls_library.txt.in b/man/coap_tls_library.txt.in index bf37d9d1..f79a9ce7 100644 --- a/man/coap_tls_library.txt.in +++ b/man/coap_tls_library.txt.in @@ -12,7 +12,7 @@ NAME ---- coap_tls_library, coap_dtls_is_supported, coap_tls_is_supported, coap_get_tls_library_version -- work with CoAP contexts +- Work with CoAP contexts SYNOPSIS -------- @@ -41,7 +41,7 @@ as detect what is the version of the currently loaded TLS library is. 1.1.0. Network traffic can be encrypted or un-encrypted with libcoap - how to set -this up is described in coap_context(3). +this up is described in *coap_context*(3). Due to the nature of TLS, there can be Callbacks that are invoked as the TLS session negotiates encryption algorithms, encryption keys etc.