mirror of
https://github.com/obgm/libcoap.git
synced 2026-11-12 11:40:39 +03:00
Merge pull request #237 from mrdeep1/doxygen-man
Include man pages into Doxygen. Add landing page for Doxygen
This commit is contained in:
25 files changed
+171
-28
No files matched your search
@@ -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
|
||||
|
||||
|
||||
+1
-1
@@ -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
|
||||
|
||||
+2
-1
@@ -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
|
||||
"
|
||||
|
||||
|
||||
+7
-5
@@ -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.
|
||||
|
||||
+4
-1
@@ -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
|
||||
|
||||
|
||||
Executable
+88
@@ -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 ' <tab type="usergroup" visible="yes" url="@ref manpage" title="Manual Pages" intro="">' > 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 ' <table class="directory">' >> 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 " <tab type=\"user\" visible=\"yes\" url=\"@ref man_$BASE\" title=\"$MANUAL - $SUMMARY\" intro=\"\"/>" >> insert_file
|
||||
|
||||
#
|
||||
# Update the summary man page
|
||||
#
|
||||
echo " <tr id=\"row_${ID}_\"$ROW_EVEN>" >> man_tmp/manpage.dox
|
||||
echo " <td class=\"entry\" align=\"left\"> @ref man_$BASE </td><td class=\"desc\" align=\"left\">$MANUAL - $SUMMARY</td>" >> man_tmp/manpage.dox
|
||||
echo " </tr>" >> 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 ' </table>' >> man_tmp/manpage.dox
|
||||
echo ' */' >> man_tmp/manpage.dox
|
||||
|
||||
#
|
||||
# Close off the insert_file
|
||||
#
|
||||
echo ' </tab>' >> insert_file
|
||||
echo ' <tab type="user" visible="yes" url="@ref deprecated" title="Deprecated Items" intro=""/>' >> insert_file
|
||||
|
||||
#
|
||||
# Create and Update the DoxygenLayout.xml file
|
||||
#
|
||||
doxygen -l
|
||||
sed -i 's/<tab type="pages" visible="yes" /<tab type="pages" visible="no" /g' DoxygenLayout.xml
|
||||
sed -i '/<tab type="examples" visible=.*/r insert_file' DoxygenLayout.xml
|
||||
rm insert_file
|
||||
|
||||
#
|
||||
# Fix up man html files, fixing links and UC Name and Synopsis
|
||||
#
|
||||
for FILE in $FILES ; do
|
||||
BASE=`echo $FILE | cut -d. -f 1`
|
||||
cat ../man/$BASE.html | sed 's^<h2>Name</h2>^<h2>NAME</h2>^g' | sed 's^<h2>Synopsis</h2>^<h2>SYNOPSIS</h2>^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^<span class=\"strong\"><strong>$EBASE</strong></span>($SECTION)^<a href=\"man_$EBASE.html\" target=\"_self\"><span class=\"strong\"><strong>$EBASE</strong></span>($SECTION)</a>^g" man_html/$BASE.html
|
||||
done
|
||||
done
|
||||
+34
@@ -0,0 +1,34 @@
|
||||
libcoap {#mainpage}
|
||||
=======
|
||||
|
||||
A C implementation of the Constrained Application Protocol (RFC 7252)
|
||||
=====================================================================
|
||||
|
||||
Copyright (C) 2010--2018 by Olaf Bergmann <bergmann@tzi.org> 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 <http://coap.technology>.
|
||||
|
||||
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.
|
||||
@@ -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__)
|
||||
|
||||
|
||||
@@ -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].
|
||||
|
||||
@@ -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
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
||||
+1
-1
@@ -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
|
||||
|
||||
@@ -17,6 +17,7 @@
|
||||
|
||||
/**
|
||||
* @defgroup prng Pseudo Random Numbers
|
||||
* API functions for gerating pseudo random numbers
|
||||
* @{
|
||||
*/
|
||||
|
||||
|
||||
+4
-1
@@ -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
|
||||
+5
-1
@@ -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
|
||||
-----------
|
||||
|
||||
@@ -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
|
||||
--------
|
||||
|
||||
@@ -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
|
||||
--------
|
||||
|
||||
@@ -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
|
||||
--------
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
--------
|
||||
|
||||
@@ -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
|
||||
--------
|
||||
|
||||
@@ -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
|
||||
--------
|
||||
|
||||
@@ -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
|
||||
--------
|
||||
|
||||
@@ -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
|
||||
--------
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user