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.