cdocumentationdoxygen
Some Newly Added Functions Are Not Documented
Problem (briefly)
Documented functions are not listed on the related group page, but listed on the file's page. One of the functions listed on the file's page does not have documantation despite it is doumented in the source file.
Details
I'm using Doxygen v1.9.2 to document an embedded application written in C. I also use git as versioning tool. I had documented the code for example in v2.0.0 and everything was ok. Recently I made some improvements and added 2 new files and new functionalities in the application. I documented the newly added files as per instruction of doxygen and some stackoverflow topics, but I did not figure out why the new file is partially documented. Since the project is a little large relatively, I will try to illustrate the documentation structure and add only issue related parts to avoid crowd and focus to the issue.
Necessarily sharing he Doxyfile config; comments, blank lines and some directory paths are omitted for brevity:
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = "Himtec Kontrol BLE"
PROJECT_NUMBER = 2.1.0
PROJECT_BRIEF = "Bluetooth Low Energy ile kontrol uygulaması"
PROJECT_LOGO = <Project-Dir>/himtec_kontrol_ble/belgelendirme/himlogo.png
OUTPUT_DIRECTORY = <Project-Dir>/Bellenim/himtec_kontrol_ble/belgelendirme/belg-v210
CREATE_SUBDIRS = NO
ALLOW_UNICODE_NAMES = NO
OUTPUT_LANGUAGE = Turkish
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ABBREVIATE_BRIEF = "The $name class" \
"The $name widget" \
"The $name file" \
is \
provides \
specifies \
contains \
represents \
a \
an \
the
ALWAYS_DETAILED_SEC = NO
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = YES
STRIP_FROM_PATH =
STRIP_FROM_INC_PATH =
SHORT_NAMES = NO
JAVADOC_AUTOBRIEF = NO
JAVADOC_BANNER = NO
QT_AUTOBRIEF = NO
MULTILINE_CPP_IS_BRIEF = NO
PYTHON_DOCSTRING = YES
INHERIT_DOCS = YES
SEPARATE_MEMBER_PAGES = NO
TAB_SIZE = 4
ALIASES =
OPTIMIZE_OUTPUT_FOR_C = YES
OPTIMIZE_OUTPUT_JAVA = NO
OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
OPTIMIZE_OUTPUT_SLICE = NO
EXTENSION_MAPPING =
MARKDOWN_SUPPORT = YES
TOC_INCLUDE_HEADINGS = 5
AUTOLINK_SUPPORT = YES
BUILTIN_STL_SUPPORT = NO
CPP_CLI_SUPPORT = NO
SIP_SUPPORT = NO
IDL_PROPERTY_SUPPORT = YES
DISTRIBUTE_GROUP_DOC = YES
GROUP_NESTED_COMPOUNDS = NO
SUBGROUPING = YES
INLINE_GROUPED_CLASSES = NO
INLINE_SIMPLE_STRUCTS = NO
TYPEDEF_HIDES_STRUCT = NO
LOOKUP_CACHE_SIZE = 0
NUM_PROC_THREADS = 1
EXTRACT_ALL = NO
EXTRACT_PRIVATE = NO
EXTRACT_PRIV_VIRTUAL = NO
EXTRACT_PACKAGE = NO
EXTRACT_STATIC = NO
EXTRACT_LOCAL_CLASSES = YES
EXTRACT_LOCAL_METHODS = NO
EXTRACT_ANON_NSPACES = NO
RESOLVE_UNNAMED_PARAMS = YES
HIDE_UNDOC_MEMBERS = NO
HIDE_UNDOC_CLASSES = NO
HIDE_FRIEND_COMPOUNDS = NO
HIDE_IN_BODY_DOCS = NO
INTERNAL_DOCS = NO
CASE_SENSE_NAMES = NO
HIDE_SCOPE_NAMES = NO
HIDE_COMPOUND_REFERENCE= NO
SHOW_HEADERFILE = YES
SHOW_INCLUDE_FILES = YES
SHOW_GROUPED_MEMB_INC = NO
FORCE_LOCAL_INCLUDES = NO
INLINE_INFO = YES
SORT_MEMBER_DOCS = YES
SORT_BRIEF_DOCS = NO
SORT_MEMBERS_CTORS_1ST = NO
SORT_GROUP_NAMES = NO
SORT_BY_SCOPE_NAME = NO
STRICT_PROTO_MATCHING = NO
GENERATE_TODOLIST = YES
GENERATE_TESTLIST = YES
GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= YES
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = YES
SHOW_FILES = YES
SHOW_NAMESPACES = YES
FILE_VERSION_FILTER =
LAYOUT_FILE =
CITE_BIB_FILES =
QUIET = NO
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_IF_INCOMPLETE_DOC = YES
WARN_NO_PARAMDOC = NO
WARN_AS_ERROR = NO
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
INPUT = . \
/home/Projeler/HimtecKontrol/Bellenim/himtec_kontrol_ble/himtec_kontrol_ble.X \
/home/Projeler/HimtecKontrol/Bellenim/himtec_kontrol_ble/himtec_kontrol_ble.X/uygulama
INPUT_ENCODING = UTF-8
FILE_PATTERNS = *.c \
*.cc \
*.cxx \
*.cpp \
*.c++ \
*.java \
*.ii \
*.ixx \
*.ipp \
*.i++ \
*.inl \
*.idl \
*.ddl \
*.odl \
*.h \
*.hh \
*.hxx \
*.hpp \
*.h++ \
*.cs \
*.d \
*.php \
*.php4 \
*.php5 \
*.phtml \
*.inc \
*.m \
*.markdown \
*.md \
*.mm \
*.dox \
*.py \
*.pyw \
*.f90 \
*.f95 \
*.f03 \
*.f08 \
*.f18 \
*.f \
*.for \
*.vhd \
*.vhdl \
*.ucf \
*.qsf \
*.ice \
*.txt
RECURSIVE = NO
EXCLUDE =
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS =
EXCLUDE_SYMBOLS =
EXAMPLE_PATH =
EXAMPLE_PATTERNS = *
EXAMPLE_RECURSIVE = NO
IMAGE_PATH =
INPUT_FILTER =
FILTER_PATTERNS =
FILTER_SOURCE_FILES = NO
FILTER_SOURCE_PATTERNS =
USE_MDFILE_AS_MAINPAGE =
SOURCE_BROWSER = YES
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
REFERENCES_LINK_SOURCE = YES
SOURCE_TOOLTIPS = YES
USE_HTAGS = NO
VERBATIM_HEADERS = YES
ALPHABETICAL_INDEX = YES
IGNORE_PREFIX =
GENERATE_HTML = YES
HTML_OUTPUT = hk-b_html
HTML_FILE_EXTENSION = .html
HTML_HEADER =
HTML_FOOTER =
HTML_STYLESHEET =
HTML_EXTRA_STYLESHEET =
HTML_EXTRA_FILES =
HTML_COLORSTYLE_HUE = 204
HTML_COLORSTYLE_SAT = 195
HTML_COLORSTYLE_GAMMA = 87
HTML_TIMESTAMP = NO
HTML_DYNAMIC_MENUS = YES
HTML_DYNAMIC_SECTIONS = NO
HTML_INDEX_NUM_ENTRIES = 100
GENERATE_DOCSET = NO
DOCSET_FEEDNAME = "Doxygen generated docs"
DOCSET_BUNDLE_ID = org.doxygen.Project
DOCSET_PUBLISHER_ID = org.doxygen.Publisher
DOCSET_PUBLISHER_NAME = Publisher
GENERATE_HTMLHELP = NO
CHM_FILE =
HHC_LOCATION =
GENERATE_CHI = NO
CHM_INDEX_ENCODING =
BINARY_TOC = NO
TOC_EXPAND = NO
GENERATE_QHP = NO
QCH_FILE =
QHP_NAMESPACE = org.doxygen.Project
QHP_VIRTUAL_FOLDER = doc
QHP_CUST_FILTER_NAME =
QHP_CUST_FILTER_ATTRS =
QHP_SECT_FILTER_ATTRS =
QHG_LOCATION =
GENERATE_ECLIPSEHELP = NO
ECLIPSE_DOC_ID = org.doxygen.Project
DISABLE_INDEX = NO
GENERATE_TREEVIEW = YES
FULL_SIDEBAR = YES
ENUM_VALUES_PER_LINE = 4
TREEVIEW_WIDTH = 250
EXT_LINKS_IN_WINDOW = NO
HTML_FORMULA_FORMAT = png
FORMULA_FONTSIZE = 10
FORMULA_TRANSPARENT = YES
FORMULA_MACROFILE =
USE_MATHJAX = NO
MATHJAX_VERSION = MathJax_2
MATHJAX_FORMAT = HTML-CSS
MATHJAX_RELPATH = https://cdn.jsdelivr.net/npm/mathjax@2
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 =
GENERATE_LATEX = NO
LATEX_OUTPUT = latex
LATEX_CMD_NAME =
MAKEINDEX_CMD_NAME = makeindex
LATEX_MAKEINDEX_CMD = makeindex
COMPACT_LATEX = NO
PAPER_TYPE = a4
EXTRA_PACKAGES =
LATEX_HEADER =
LATEX_FOOTER =
LATEX_EXTRA_STYLESHEET =
LATEX_EXTRA_FILES =
PDF_HYPERLINKS = YES
USE_PDFLATEX = YES
LATEX_BATCHMODE = NO
LATEX_HIDE_INDICES = NO
LATEX_BIB_STYLE = plain
LATEX_TIMESTAMP = NO
LATEX_EMOJI_DIRECTORY =
GENERATE_RTF = NO
RTF_OUTPUT = rtf
COMPACT_RTF = NO
RTF_HYPERLINKS = NO
RTF_STYLESHEET_FILE =
RTF_EXTENSIONS_FILE =
GENERATE_MAN = NO
MAN_OUTPUT = man
MAN_EXTENSION = .3
MAN_SUBDIR =
MAN_LINKS = NO
GENERATE_XML = NO
XML_OUTPUT = xml
XML_PROGRAMLISTING = YES
XML_NS_MEMB_FILE_SCOPE = NO
GENERATE_DOCBOOK = YES
DOCBOOK_OUTPUT = hk-b_docbook
GENERATE_AUTOGEN_DEF = NO
GENERATE_PERLMOD = NO
PERLMOD_LATEX = NO
PERLMOD_PRETTY = YES
PERLMOD_MAKEVAR_PREFIX =
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = NO
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED =
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES
TAGFILES =
GENERATE_TAGFILE =
ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
EXTERNAL_PAGES = YES
CLASS_DIAGRAMS = YES
DIA_PATH =
HIDE_UNDOC_RELATIONS = YES
HAVE_DOT = NO
DOT_NUM_THREADS = 0
DOT_FONTNAME = Helvetica
DOT_FONTSIZE = 10
DOT_FONTPATH =
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
GROUP_GRAPHS = YES
UML_LOOK = NO
UML_LIMIT_NUM_FIELDS = 10
DOT_UML_DETAILS = NO
DOT_WRAP_THRESHOLD = 17
TEMPLATE_RELATIONS = NO
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = NO
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 =
PLANTUML_CFG_FILE =
PLANTUML_INCLUDE_PATH =
DOT_GRAPH_MAX_NODES = 50
MAX_DOT_GRAPH_DEPTH = 0
DOT_TRANSPARENT = NO
DOT_MULTI_TARGETS = NO
GENERATE_LEGEND = YES
DOT_CLEANUP = YES
Sharing the header source file in which I've added and then documented recently as a whole for sake of detail:
/**
* \defgroup tilt Tilt Kontrol
* \ingroup cikis
* @{
* Yük çıkışlarını kullanarak tilt denetimi yapar.
*/
/**
* \file
*
* \author
*
*
* \date 2021.11.02
*/
#ifndef TILT_H
#define TILT_H
#include "kontrol.h"
/**
* @name Tilt İşlem Tanımlamaları
* @{
*
* Tilt denetim modülü bu tanımlamaları kullanarak tilt sürecini denetler.
*/
#define TILT_DURDU (0u)
#define TILT_ETKIN (1u)
/**
* @name Tilt Yönü Tanımlamaları
* @{
*
* Tiltin hareket yönünü belirlemek için kullanılır. Tilt yönü çıkışın son
* hareketine göre belirlenir. Son olarak açma hareketi yapıldıysa, bu aygıt
* üzerindeki açma tuşuna tilt için basıldığında tilt yönü kapatmadır, veya
* tam tersi.
*/
#define TILT_YOK KONTROL_YOK
#define TILT_AC KONTROL_AC_TERS
#define TILT_KAPAT KONTROL_KAPAT_TERS
/// @}
/**
* @name Tilt Hareket ve Bekleme Süreleri Tanımlamaları
* @{
*
* Tiltin hareket ve bekleme sürelerinin minimum ve maksimum tanımlamalarıdır.
* Bu tanımlamalarda min ve max değerleri hassasiyete göre tanımlanır. Örneğin
* hareketin 10 ms, beklemenin de 100 ms olması tilt hassasiyetini artıracağı
* için 10 ve 100 maksimum, 50 ms hareket süresi ve 500 ms bekleme süresi de
* tilt hassasiyetini azaltacağı için minimum olarak tanımlanmışlardır.
* Tilt hareketi hassasiyet olarak ölçüldüğünden, hareket ve bekleme süreleri
* birbirinden bağımsız olamaz. Hassasiyet yüzde olarak ayarlanır, ve yüzde
* değeri doğrusal dönüşüm hesaplamalarıyla denk gelen hareket ve bekleme
* sürelerine dönüştürülür.
*/
#define TILT_HAREKET_MIN_MS (50u)
#define TILT_HAREKET_MAX_MS (10u)
#define TILT_BEKLEME_MIN_MS (500u)
#define TILT_BEKLEME_MAX_MS (100u)
/// @}
/**
* @name Tilt Varsayılan Süre Tanımlamaları
* @{
*
* Fabrika açılışında tilt hassasiyeti bu değerlere kurulur. Merkezi aygıtlardan
* tilt hassasiyet ayarındaki varsayılan hassasiyet her zaman ayarlanabilir.
*/
#define TILT_VARS_HAREKET_MS (15u) ///< Varsayılan hareket süresi.
#define TILT_VARS_BEKLEME_MS (150u) ///< Varsayılan bekleme süresi
/// @}
/// @}
#if URUN_TURU == IC_MEKAN
/**
* @ingroup gorev
*
* Eylem girdilerine göre tilt sürecini yönetir.
*
* Ayarlanan hassasiyete göre tilt sürecini yönetir. Tilt süreci <code>
* tiltEylemiKur()</code> API'si kullanılarak başlatılır veya duraklatılır.
* Tilt, bu aygıt üzerindeki kumanda tuşları ve bir uzak merkezi aygıtın kumanda
* tuşları olmak üzere iki kaynaktan denetlenebilir. Kaynaklardan biri tilti
* sürmek için eriştiğinde diğer kaynaklar; ilk erişen kaynak erişimi salana
* dek tilte erişemez ve dolayısıyla denetleyemez. Bununla birlikte tilt modülü
* çıkışlara erişince kontrol modülü, çıkışlara erişmek için tiltin erişimi
* salmasını beklemek zorundadır. Bu yüzden kontrol tuşları, tilt süreci
* bitene dek çalışmaz.
*
* \warning Bu işlev Görevci tarafından yönetilen bir görev bloğudur. Uygulama
* içerisinden direk çağrılmaz. Görev bloklarını kontrol etmek için Görevci
* API'leri kullanılmalıdır. Aksi takdirde görev işlevini yitirebilir.
*
* @sa tiltHassasiyetiniYuzdeOlarakKur(), tiltEylemiKur().
*/
char tiltKontrol(gorevTutucu_t gt);
/**
* Tilt görevini sürer ve tilt modülünü kontrol eder.
*
* Tilt işlemleri bu işlev aracılığıyla yönetilir. Tilti aşağı veya yukarı yönde
* başlatma ve duraklatma bu işlev ile yapılır. Bu işleve parametre olarak şu
* eylemler verilebilir:
* <ul><li>TILT_YOK
* <li>TILT_AC
* <li>TILT_KAPAT </ul>
* Aşağıda örnek API kullanımı verilmiştir.
*
* @code
* tiltEylemiKur(TILT_AC); // Tilti açma yönünde başlatır.
* tiltEylemiKur(TILT_YOK); // Tilti duraklatır.
* tiltEylemiKur(TILT_KAPAT); // Tilti kapatma yönünde başlatır.
* @endcode
*
* @param eylem Tilti sürecek eylem.
*
* @sa TILT_YOK, TILT_AC, TILT_KAPAT.
*/
void tiltEylemiKur(uint8_t eylem);
/**
* Tilt modülünün varsayılan hassasiyetini yüzde olarak verir.
*
* @return Tilt modülünün yüzde olarak varsayılan hassasiyeti.
*/
uint8_t tiltVarsHassasiyet(void);
/**
* Tilt modülünün güncel hassasiyetini yüzde olarak verir.
*
* @return Tilt modülünün yüzde olarak güncel hassasiyeti.
*/
uint8_t tiltHassasiyeti(void);
/**
* Tilt modülünün hassasiyetini kurar.
*
* Tilt modülünün hassasiyeti tiltin ne kadar hızlı adımlayacağını belirler.
* Tilt ne kadar hassas ayarlanırsa adımlama hızı o kadar küçük, hassasiyet ne
* kadar az olursa adımlama hızı o kadar büyük olacaktır.
*
* @param deger Tilt modülünün hassasiyetini belirleyecek 0 - 100 arası bir değer.
*/
void tiltHassasiyetiniYuzdeOlarakKur(uint8_t deger);
/**
* Tilt modülünün kayıttan alınan hassasiyet değerini kurar.
*
* Hassasiyet yüzde değeri kalıcı bellekte saklanır. Bu işlev aracılığıyla,
* ilk açılış sonrası her sistem açılışında kayıttan okunan hassasiyet değeri
* tilt modülüne yazılır.
*
* @param hass Kayıttan okunan hassasiyet yüzde değeri.
*/
void tiltKayittanHassKur(uint8_t hass);
/**
* Tilt modülünün kayıttan alınan hareket süresini kurar.
*
* @param sure Kayıttan okunan güncel hareket süresi.
*/
void tiltKayittanHareketSuresiKur(uint8_t sure);
/**
* Tilt modülünün kayıttan alınan bekleme süresini kurar.
*
* @param sure Kayıttan okunan güncel bekleme süresi.
*/
void tiltKayittanBeklemeSuresiKur(uint16_t sure);
#endif
#endif /* TILT_H */
/** @} */
Last but not least, a screenshot of the output html to show the issue clearly:
This is the extracted grouping definition hierarchy up to the problematic doc file:
1. \defgroup himk Himtek Kontrol
2. \defgroup cikis Çıkış Yönetimi
3. \ingroup himk
4. \defgroup tilt Tilt Kontrol
5. \ingroup cikis
The definitions number 4 and 5 are made in file named tilt.h whose functions are not listed in the "Tilt Kontrol" output html page (see the screenshot above). But if I open tilt.h file from that page's file url,
the functions are did listed and documented there;
except 1 function named "tiltEylemiKur" is listed but its documentation is not shown.
If you have a look at the source file above you will see that function is documented in the source file, but not documented on the output page.
Solution
Thanks to @albert for pointing out the problem. Although he preferred not to answer, I will leave this answer for anyone who may have the same problem in the future.
The problem here was that I was using nested Member Groups using the @name command which is currently not allowed by doxygen (Don't know, it may change in the future). Here is a snippet which shows the problem:
/**
* @name Some Member Title
* @{
* Some description...
*/
Member definitons...
/**
* @name A Nested Member Title
* @{
* Some description for nested member grouping...
* This inner grouping is not allowed and can ruin the rest of the documentation
*/
Another member definitons...
/// @}
/// @}
Well the solution as you can guess is, just to not nesting the member groups. See the following fixed documentation snippet:
/**
* @name Some Member Groups Title
* @{
* Some description for member groups (optional)...
*/
/**
* The documentation of this particular member
*/
Member definitons...
/**
* The documentation of this particular member
*/
Another member definitons...
/// @}
- Difference between sqrt(x) and pow(x,0.5)
- Can you explain this 'Hello world' program?
- how can i check file write permissions in C++ code?
- Compare floating point numbers as integers
- Ninja Build System + gcc/clang doesn't output diagnostic colors
- Why does my C program give an error when looping through an array?
- Printing char array with null character in the middle in C
- How do I read the source code for a C library in CLion
- pthread nice value setting for default scheduler in C
- Use a 3d array on a function (array that contains arrays that contain strings)
- frida-server being targeted by port scan?
- Are compound literals always lvalue?
- Why is the beginning of a C file stream called `SEEK_SET`?
- How to Take whitespace in Input in C
- "undefined reference to" errors when linking static C library with C++ code
- Audio timescale-pitch modification - Open source examples?
- What is the easiest way to create a secured network client in Linux (C) without any external libraries?
- Are there any non-twos-complement implementations of C?
- Read variable value from PE file
- C: Memory Allocation on Stack for Nested Structures
- The max number of digits in an int based on number of bits
- Aliasing struct and array the C++ way
- AC_SEARCH_LIBS on a static library that itself has dependencies?
- What is the relation between operator precedence and order of evaluation?
- Why does my getop function in C return '+' correctly but not '=' when there are leading spaces?
- How to efficiently compare a block of memory to a single byte?
- What is the most elegant way to work with global variables in an embedded system?
- sqrt is only defined when argument is nonnegative
- How do you get the network interface index for the loopback interface?
- use of -mcmodel=kernel flag in x86 platform