kecx --- KEyed Comment eXtractor

Using this library

Simply include this library as a sub-dir in your project and include ./include/kecx/kecx.hpp in your code. E.g. in a directory structure

my_project
    my_file.hpp
    kecx/
        include/
            kecx/
                kecx.hpp
                ...

you can use this line in my_file.hpp:

#include "./kecx/include/kecx/kecx.hpp"

Features

The main feature of this library is extraction of documentation contained within comments. This library does not prepare .html or other documents for you --- it simply extracts what you have written into comments into a location of your choice. Normally you would extract documentation from your comments into text files and produce a larger document out of the smaller ones. This README.md has been produced simply by extracting documentation comments from source files directly into the README.md.

Main functions

You may only need kecx::extract::extract or one of its signatures, which currently vary wrt. the first argument (file_path / file_paths) and arg store.

Single file, arbitrary store callback function store

*
     * @brief
     * Extract commented documentation from a single text file.
     * @param file_path
     * Path to file from which to extract documentation.
     * @param multiline_comment_start
     * Regex to identify multiline comment starts, e.g. "[/][*]".
     * @param multiline_comment_stop
     * Regex to identify multiline comment stops, e.g. "[*][/]".
     * @param singleline_comment
     * Regex to identify single line comments, e.g. "".
     * @param header_only_tag_set
     * @param header_tag_set
     * @param footer_tag_set
     * @param either_tag_set
     * Tags considered "either", i.e. both header and footer tags.
     * @param store
     * Storage method, here an arbitrary callback function.
     * First three arguments reserved for `key`, `line`, and `line_no`.
     * @param store_only_comments_ho
     * If `true`, only comment lines are stored for header-only blocks.
     * @param store_only_comments_hf
     * If `true`, only comment lines are stored for header-footer blocks.
     * @param store_only_comments_e
     * If `true`, only comment lines are stored for "either" blocks.
     * @param verbosity
     * For debugging.

    void extract(
        const std::string& file_path,
        const std::string& multiline_comment_start,
        const std::string& multiline_comment_stop,
        const std::string& singleline_comment,
        const std::vector<std::string>& header_only_tag_set,
        const std::vector<std::string>& header_tag_set,
        const std::vector<std::string>& footer_tag_set,
        const std::vector<std::string>& either_tag_set,
        const store::store_type& store = store::store_default,
        const bool& store_only_comments_ho = true,
        const bool& store_only_comments_hf = false,
        const bool& store_only_comments_e  = false,
        const int& verbosity = 0
    )

Single file, write results into text files in directory store

*
     * @brief
     * Extract commented documentation from a single text file.
     * Write extracted texts into dir `store` --- one file for each key.
     * @param file_path
     * Path to file from which to extract documentation.
     * @param multiline_comment_start
     * Regex to identify multiline comment starts, e.g. "[/][*]".
     * @param multiline_comment_stop
     * Regex to identify multiline comment stops, e.g. "[*][/]".
     * @param singleline_comment
     * Regex to identify single line comments, e.g. "".
     * @param header_only_tag_set
     * @param header_tag_set
     * @param footer_tag_set
     * @param either_tag_set
     * Tags considered "either", i.e. both header and footer tags.
     * @param store
     * Here a path to a directory into which one text file will be written for
     * each key.
     * @param store_only_comments_ho
     * If `true`, only comment lines are stored for header-only blocks.
     * @param store_only_comments_hf
     * If `true`, only comment lines are stored for header-footer blocks.
     * @param store_only_comments_e
     * If `true`, only comment lines are stored for "either" blocks.
     * @param verbosity
     * For debugging.

    void extract(
        const std::string& file_path,
        const std::string& multiline_comment_start,
        const std::string& multiline_comment_stop,
        const std::string& singleline_comment,
        const std::vector<std::string>& header_only_tag_set,
        const std::vector<std::string>& header_tag_set,
        const std::vector<std::string>& footer_tag_set,
        const std::vector<std::string>& either_tag_set,
        const std::string& store,
        const bool& store_only_comments_ho = true,
        const bool& store_only_comments_hf = false,
        const bool& store_only_comments_e  = false,
        const int& verbosity = 0
    )

Multiple files, store templated out

*
     * @brief
     * Extract commented documentation from a single text file.
     * Write extracted texts into dir `store` --- one file for each key.
     * @param file_paths
     * One or more file paths to process.
     * @param multiline_comment_start
     * Regex to identify multiline comment starts, e.g. "[/][*]".
     * @param multiline_comment_stop
     * Regex to identify multiline comment stops, e.g. "[*][/]".
     * @param singleline_comment
     * Regex to identify single line comments, e.g. "".
     * @param header_only_tag_set
     * @param header_tag_set
     * @param footer_tag_set
     * @param either_tag_set
     * Tags considered "either", i.e. both header and footer tags.
     * @param store
     * See other signatures.
     * @param store_only_comments_ho
     * If `true`, only comment lines are stored for header-only blocks.
     * @param store_only_comments_hf
     * If `true`, only comment lines are stored for header-footer blocks.
     * @param store_only_comments_e
     * If `true`, only comment lines are stored for "either" blocks.
     * @param verbosity
     * For debugging.

    template<typename T>
    void extract(
        const std::vector<std::string>& file_paths,
        const std::string& multiline_comment_start,
        const std::string& multiline_comment_stop,
        const std::string& singleline_comment,
        const std::vector<std::string>& header_only_tag_set,
        const std::vector<std::string>& header_tag_set,
        const std::vector<std::string>& footer_tag_set,
        const std::vector<std::string>& either_tag_set,
        const T& store,
        const bool& store_only_comments_ho = true,
        const bool& store_only_comments_hf = false,
        const bool& store_only_comments_e  = false,
        const int& verbosity = 0
    )

Examples

See the following files for examples:

• ./doc/make_readme.sh: A simple shell script which compiles a tiny c++ programme that in turn makes README.md.
• ./doc/make_readme.cpp: A tiny c++ programme to populate README.md.
• ./examples/example_01.cpp: A straightforward example of extracting various kinds of keyed comments from ./examples/data/input_01.cpp.
• ./examples/example_02.cpp: Extract doxygen comments in ./examples/data/input_02.cpp into separate text files --- though some clean-up work remains. Also, multiple function definitions in the same file would currently be a problem as arguments with the same name would be inserted into the same output file.
• ./examples/example_03.cpp: You can actually use kecx for other purposes also though this was not on purpose. Here is shown how you can separate ./examples/data/input_02.md into separate files by section.