当前,我正在研究项目文档。当我在conf.py中包含源文件和头文件时,HTML成功生成。但是,当我只想将源文件用于文档HTML文件时,就出了点问题。如以下
我的conf.py内容如下,
# Setup the exhale extension
exhale_args = {
# These arguments are required
"containmentFolder": "./api",
"rootFileName": "library_root.rst",
"rootFileTitle": "Library API",
"doxygenStripFromPath": "..",
# Suggested optional arguments
"createTreeView": True,
# TIP: if using the sphinx-bootstrap-theme, you need
# "treeViewIsBootstrap": True,
"exhaleExecutesDoxygen": True,
"exhaleDoxygenStdin": textwrap.dedent('''
EXTRACT_ALL = YES
SOURCE_BROWSER = YES
EXTRACT_STATIC = YES
OPTIMIZE_OUTPUT_FOR_C = YES
HIDE_SCOPE_NAMES = YES
QUIET = YES
INPUT = ../include ../src
FILE_PATTERNS = *.c *.h
EXAMPLE_RECURSIVE = YES
GENERATE_TREEVIEW = YES
''')
}
具有成功结果的源文件和头文件
[源文件]
/**
* @brief Fills the data buffer
* @param[in] Data buffer
* @return pointer to the data buffer
**/
char* at_test_action(void* data)
{
char* ptr = (char*) data;
sprintf( ptr, "AT\r\n" );
return ptr;
}
[头文件]
#ifndef TEST_H
#define TEST_H
#ifdef __cplusplus
extern "C" {
#endif
char* at_test_action(void* data);
#ifdef __cplusplus
}
#endif
#endif /* TEST_H */
结果失败的源文件和头文件
[源文件]
/**
* @brief Fills the data buffer
* @param[in] Data buffer
* @return pointer to the data buffer
**/
char* at_test_action(void* data)
{
char* ptr = (char*) data;
sprintf( ptr, "AT\r\n" );
return ptr;
}
[头文件]
#ifndef TEST_H
#define TEST_H
#ifdef __cplusplus
extern "C" {
#endif
// char* at_test_action(void* data);
#ifdef __cplusplus
}
#endif
#endif /* TEST_H */
我可以使用没有头文件的Doxygen生成我想要的结果。 非常感谢。
2020.01.31更新(UTC时间:02:51)
由于文档重复,我想在标题文件中添加以下注释。 http://doxygen.10944.n7.nabble.com/Remove-detailed-documentation-from-header-td3679.html
[头文件]
#ifndef TEST_H
#define TEST_H
#ifdef __cplusplus
extern "C" {
#endif
/* @cond INCLUDE_THIS_SECTION_IN_DOXYGEN_OUTPUT */
char* at_test_action(void* data);
/* @endcond */
#ifdef __cplusplus
}
#endif
#endif /* TEST_H */
[源文件]
/**
* \brief Fills the data buffer
* \param[in] data data buffer for content preparation
* \return pointer to the data buffer
**/
char* at_test_action(void* data)
{
char* ptr = (char*) data;
sprintf( ptr, "AT\r\n" );
return ptr;
}
Doxygen结果不超过@cond,如下所示。实际上,用Doxygen表示对我有好处。
但是,当更改为Sphinx表示形式时,用户将看到两个相同的功能,并在侧边栏列出,而没有任何详细信息可区分它:
对于这些工具,我还是陌生的,如果有愚蠢的问题或信息不足,请告诉我。非常感谢。
答案 0 :(得分:0)
一个问题是@param
语句与doxygen的用法不正确。语法为\param '['dir']' <parameter-name> { parameter description }
。
在您的示例中,参数名称为Data
,而实际上参数为data
。据我所知,您的预期用途是@param[in] data Data buffer
。