From 3b3e14d056650cde7c753e1e88bc220951d7de32 Mon Sep 17 00:00:00 2001 From: Michal Virgovic Date: Mon, 24 Jul 2017 16:08:49 +0200 Subject: [PATCH] Update doxygen documentation for version 1.8. --- docs/doxyfile | 75 ++++++++++++++++++------- docs/{doxygen_index => doxygen_index.h} | 21 +------ 2 files changed, 57 insertions(+), 39 deletions(-) rename docs/{doxygen_index => doxygen_index.h} (95%) diff --git a/docs/doxyfile b/docs/doxyfile index 1257effa..a8c84db4 100644 --- a/docs/doxyfile +++ b/docs/doxyfile @@ -1,4 +1,4 @@ -# Doxyfile 1.7.4 +# Doxyfile 1.8.8 #--------------------------------------------------------------------------- # Project related configuration options @@ -10,6 +10,7 @@ PROJECT_BRIEF = "Public cryptsetup API" PROJECT_LOGO = OUTPUT_DIRECTORY = doxygen_api_docs CREATE_SUBDIRS = NO +ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES @@ -27,11 +28,14 @@ INHERIT_DOCS = YES SEPARATE_MEMBER_PAGES = NO TAB_SIZE = 8 ALIASES = +TCL_SUBST = OPTIMIZE_OUTPUT_FOR_C = YES OPTIMIZE_OUTPUT_JAVA = NO OPTIMIZE_FOR_FORTRAN = NO OPTIMIZE_OUTPUT_VHDL = NO EXTENSION_MAPPING = +MARKDOWN_SUPPORT = YES +AUTOLINK_SUPPORT = YES BUILTIN_STL_SUPPORT = NO CPP_CLI_SUPPORT = NO SIP_SUPPORT = NO @@ -39,13 +43,15 @@ IDL_PROPERTY_SUPPORT = YES DISTRIBUTE_GROUP_DOC = NO SUBGROUPING = YES INLINE_GROUPED_CLASSES = NO +INLINE_SIMPLE_STRUCTS = NO TYPEDEF_HIDES_STRUCT = YES -SYMBOL_CACHE_SIZE = 0 +LOOKUP_CACHE_SIZE = 0 #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- EXTRACT_ALL = NO EXTRACT_PRIVATE = NO +EXTRACT_PACKAGE = NO EXTRACT_STATIC = NO EXTRACT_LOCAL_CLASSES = YES EXTRACT_LOCAL_METHODS = NO @@ -58,6 +64,7 @@ INTERNAL_DOCS = NO CASE_SENSE_NAMES = YES HIDE_SCOPE_NAMES = NO SHOW_INCLUDE_FILES = YES +SHOW_GROUPED_MEMB_INC = NO FORCE_LOCAL_INCLUDES = NO INLINE_INFO = YES SORT_MEMBER_DOCS = YES @@ -73,13 +80,13 @@ GENERATE_DEPRECATEDLIST= YES ENABLED_SECTIONS = MAX_INITIALIZER_LINES = 30 SHOW_USED_FILES = YES -SHOW_DIRECTORIES = NO SHOW_FILES = YES SHOW_NAMESPACES = YES FILE_VERSION_FILTER = LAYOUT_FILE = +CITE_BIB_FILES = #--------------------------------------------------------------------------- -# configuration options related to warning and progress messages +# Configuration options related to warning and progress messages #--------------------------------------------------------------------------- QUIET = NO WARNINGS = YES @@ -89,9 +96,10 @@ WARN_NO_PARAMDOC = NO WARN_FORMAT = "$file:$line: $text" WARN_LOGFILE = #--------------------------------------------------------------------------- -# configuration options related to the input files +# Configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = "doxygen_index" "../lib/libcryptsetup.h" +INPUT = "doxygen_index.h" \ + "../lib/libcryptsetup.h" INPUT_ENCODING = UTF-8 FILE_PATTERNS = RECURSIVE = NO @@ -107,8 +115,9 @@ INPUT_FILTER = FILTER_PATTERNS = FILTER_SOURCE_FILES = NO FILTER_SOURCE_PATTERNS = +USE_MDFILE_AS_MAINPAGE = #--------------------------------------------------------------------------- -# configuration options related to source browsing +# Configuration options related to source browsing #--------------------------------------------------------------------------- SOURCE_BROWSER = NO INLINE_SOURCES = NO @@ -116,16 +125,19 @@ STRIP_CODE_COMMENTS = YES REFERENCED_BY_RELATION = NO REFERENCES_RELATION = NO REFERENCES_LINK_SOURCE = YES +SOURCE_TOOLTIPS = YES USE_HTAGS = NO VERBATIM_HEADERS = YES +CLANG_ASSISTED_PARSING = NO +CLANG_OPTIONS = #--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index +# Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- ALPHABETICAL_INDEX = YES COLS_IN_ALPHA_INDEX = 5 IGNORE_PREFIX = #--------------------------------------------------------------------------- -# configuration options related to the HTML output +# Configuration options related to the HTML output #--------------------------------------------------------------------------- GENERATE_HTML = YES HTML_OUTPUT = html @@ -133,13 +145,14 @@ HTML_FILE_EXTENSION = .html HTML_HEADER = HTML_FOOTER = HTML_STYLESHEET = +HTML_EXTRA_STYLESHEET = HTML_EXTRA_FILES = HTML_COLORSTYLE_HUE = 220 HTML_COLORSTYLE_SAT = 100 HTML_COLORSTYLE_GAMMA = 80 HTML_TIMESTAMP = YES -HTML_ALIGN_MEMBERS = YES HTML_DYNAMIC_SECTIONS = NO +HTML_INDEX_NUM_ENTRIES = 100 GENERATE_DOCSET = NO DOCSET_FEEDNAME = "Doxygen generated docs" DOCSET_BUNDLE_ID = org.doxygen.Project @@ -163,19 +176,26 @@ QHG_LOCATION = GENERATE_ECLIPSEHELP = NO ECLIPSE_DOC_ID = org.doxygen.Project DISABLE_INDEX = NO -ENUM_VALUES_PER_LINE = 4 GENERATE_TREEVIEW = NO -USE_INLINE_TREES = NO +ENUM_VALUES_PER_LINE = 4 TREEVIEW_WIDTH = 250 EXT_LINKS_IN_WINDOW = NO FORMULA_FONTSIZE = 10 FORMULA_TRANSPARENT = YES USE_MATHJAX = NO +MATHJAX_FORMAT = HTML-CSS MATHJAX_RELPATH = http://www.mathjax.org/mathjax +MATHJAX_EXTENSIONS = +MATHJAX_CODEFILE = SEARCHENGINE = YES SERVER_BASED_SEARCH = NO +EXTERNAL_SEARCH = NO +SEARCHENGINE_URL = +SEARCHDATA_FILE = searchdata.xml +EXTERNAL_SEARCH_ID = +EXTRA_SEARCH_MAPPINGS = #--------------------------------------------------------------------------- -# configuration options related to the LaTeX output +# Configuration options related to the LaTeX output #--------------------------------------------------------------------------- GENERATE_LATEX = YES LATEX_OUTPUT = latex @@ -186,13 +206,15 @@ PAPER_TYPE = a4 EXTRA_PACKAGES = LATEX_HEADER = LATEX_FOOTER = +LATEX_EXTRA_FILES = PDF_HYPERLINKS = YES USE_PDFLATEX = YES LATEX_BATCHMODE = NO LATEX_HIDE_INDICES = NO LATEX_SOURCE_CODE = NO +LATEX_BIB_STYLE = plain #--------------------------------------------------------------------------- -# configuration options related to the RTF output +# Configuration options related to the RTF output #--------------------------------------------------------------------------- GENERATE_RTF = NO RTF_OUTPUT = rtf @@ -201,26 +223,31 @@ RTF_HYPERLINKS = NO RTF_STYLESHEET_FILE = RTF_EXTENSIONS_FILE = #--------------------------------------------------------------------------- -# configuration options related to the man page output +# Configuration options related to the man page output #--------------------------------------------------------------------------- GENERATE_MAN = NO MAN_OUTPUT = man MAN_EXTENSION = .3 +MAN_SUBDIR = MAN_LINKS = NO #--------------------------------------------------------------------------- -# configuration options related to the XML output +# Configuration options related to the XML output #--------------------------------------------------------------------------- GENERATE_XML = NO XML_OUTPUT = xml -XML_SCHEMA = -XML_DTD = XML_PROGRAMLISTING = YES #--------------------------------------------------------------------------- -# configuration options for the AutoGen Definitions output +# Configuration options related to the DOCBOOK output +#--------------------------------------------------------------------------- +GENERATE_DOCBOOK = NO +DOCBOOK_OUTPUT = docbook +DOCBOOK_PROGRAMLISTING = NO +#--------------------------------------------------------------------------- +# Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- GENERATE_AUTOGEN_DEF = NO #--------------------------------------------------------------------------- -# configuration options related to the Perl module output +# Configuration options related to the Perl module output #--------------------------------------------------------------------------- GENERATE_PERLMOD = NO PERLMOD_LATEX = NO @@ -239,18 +266,20 @@ PREDEFINED = EXPAND_AS_DEFINED = SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- -# Configuration::additions related to external references +# Configuration options related to external references #--------------------------------------------------------------------------- TAGFILES = GENERATE_TAGFILE = ALLEXTERNALS = NO EXTERNAL_GROUPS = YES +EXTERNAL_PAGES = YES PERL_PATH = #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- CLASS_DIAGRAMS = YES MSCGEN_PATH = +DIA_PATH = HIDE_UNDOC_RELATIONS = YES HAVE_DOT = NO DOT_NUM_THREADS = 0 @@ -261,6 +290,7 @@ CLASS_GRAPH = YES COLLABORATION_GRAPH = YES GROUP_GRAPHS = YES UML_LOOK = NO +UML_LIMIT_NUM_FIELDS = 10 TEMPLATE_RELATIONS = NO INCLUDE_GRAPH = YES INCLUDED_BY_GRAPH = YES @@ -269,9 +299,12 @@ CALLER_GRAPH = NO GRAPHICAL_HIERARCHY = YES DIRECTORY_GRAPH = YES DOT_IMAGE_FORMAT = png +INTERACTIVE_SVG = NO DOT_PATH = DOTFILE_DIRS = MSCFILE_DIRS = +DIAFILE_DIRS = +PLANTUML_JAR_PATH = DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 DOT_TRANSPARENT = NO diff --git a/docs/doxygen_index b/docs/doxygen_index.h similarity index 95% rename from docs/doxygen_index rename to docs/doxygen_index.h index d75ce0f9..75c5f097 100644 --- a/docs/doxygen_index +++ b/docs/doxygen_index.h @@ -1,7 +1,6 @@ -/** - * @mainpage Cryptsetup API +/*! \mainpage Cryptsetup API * - * The documentation covers public parts of cryptsetup API. In the following sections you'll find + * The documentation covers public parts of cryptsetup API. In the following sections you'll find * the examples that describe some features of cryptsetup API. * For more info about libcryptsetup API versions see * API Tracker. @@ -32,15 +31,13 @@ * @section cexamples Cryptsetup API examples * @section cluks crypt_luks_usage - cryptsetup LUKS device type usage * @subsection cinit crypt_init() - * - * Every time you need to do something with cryptsetup or dmcrypt device + * Every time you need to do something with cryptsetup or dmcrypt device * you need a valid context. The first step to start your work is * @ref crypt_init call. You can call it either with path * to the block device or path to the regular file. If you don't supply the path, * empty context is initialized. * * @subsection cformat crypt_format() - header and payload on mutual device - * * This section covers basic use cases for formatting LUKS devices. Format operation * sets device type in context and in case of LUKS header is written at the beginning * of block device. In the example bellow we use the scenario where LUKS header and data @@ -51,7 +48,6 @@ * overwrites part of the backing block device. * * @subsection ckeys Keyslot operations examples - * * After successful @ref crypt_format of LUKS device, volume key is not stored * in a persistent way on the device. Keyslot area is an array beyond LUKS header, where * volume key is stored in the encrypted form using user input passphrase. For more info about @@ -60,33 +56,27 @@ * There are two basic methods to create a new keyslot: * * @subsection ckeyslot_vol crypt_keyslot_add_by_volume_key() - * * Creates a new keyslot directly by encrypting volume_key stored in the device * context. Passphrase should be supplied or user is prompted if passphrase param is * NULL. * * @subsection ckeyslot_pass crypt_keyslot_add_by_passphrase() - * * Creates a new keyslot for the volume key by opening existing active keyslot, * extracting volume key from it and storing it into a new keyslot * protected by a new passphrase * * @subsection cload crypt_load() - * * Function loads header from backing block device into device context. * * @subsection cactivate crypt_activate_by_passphrase() - * * Activates crypt device by user supplied password for keyslot containing the volume_key. * If keyslot parameter is set to CRYPT_ANY_SLOT then all active keyslots * are tried one by one until the volume key is found. * * @subsection cactive_pars crypt_get_active_device() - * * This call returns structure containing runtime attributes of active device. * * @subsection cinit_by_name crypt_init_by_name() - * * In case you need to do operations with active device (device which already * has its corresponding mapping) and you miss valid device context stored in * *crypt_device reference, you should use this call. Function tries to @@ -94,22 +84,18 @@ * header. * * @subsection cdeactivate crypt_deactivate() - * * Deactivates crypt device (removes DM mapping and safely erases volume key from kernel). * * @subsection cluks_ex crypt_luks_usage.c - Complex example - * * To compile and run use following commands in examples directory: * * @code * make * ./crypt_luks_usage _path_to_[block_device]_file * @endcode - * * Note that you need to have the cryptsetup library compiled. @include crypt_luks_usage.c * * @section clog crypt_log_usage - cryptsetup logging API example - * * Example describes basic use case for cryptsetup logging. To compile and run * use following commands in examples directory: * @@ -117,7 +103,6 @@ * make * ./crypt_log_usage * @endcode - * * Note that you need to have the cryptsetup library compiled. @include crypt_log_usage.c * * @example crypt_luks_usage.c