I am attempting my first documentation using Doxygen. My firmware is written in c. I have documented the main file and I want to document a library. The library has a .c and .h file.
How could I document the library?
Should I define two independed groups using the #defgroup?
For example for the .c file:
** #defgroup ble_raw_data.c
* #{
*/
and for the .h file:
** #defgroup ble_raw_data.h
* #{
*/
Is this correct? Or is there any more elegant approach?
Thanks in advance
Nick
Related
I have a fair understanding of both how to document code and how to write "generic documentation" using #mainpage, #page, #subpage and related tags.
I would need to include requirements/specification documentation for the code.
My problem is to keep this kind of documentation (conceptually distinct from code documentation) close to code implementing functionality (i.e.: at least in the same file, sometimes even near specific classes/functions/methods) but still be able to collect it in an orderly fashion and present it in the #mainpage, outside file/class hierarchy.
What I would ideally need is to be able to place specific #page, #section, #subsection etc. randomly in the various source files and then be able to #include them in a specific order into #mainpage or some other #subpage.
Even better would be to be able to include the same snippet in both class/function full doc (not #brief, of course) and in the "front matter" linked in #mainpage.
Global effect I need to have is to have a "specification document" where I detail what the various parts of the code need to implement and then the "normal class/function/whatever" documentation doxygen id very good at providing.
The catch (i.e.: what I don't know how to do) is I would like to keep "specification" and implementation together in the source, but separate them in documentation, i.e.:
General Description: easy, this goes into #mainpage
Requirements: most likely at top of source file implementing them, how do I link/include in main page?
Specification: either right after Requirements at top of file or somewhere near class/function implementing it; also here I don't know how to link/include in "front matter" AKA: #mainpage.
Normal code documentation: here only thing I don't know is how include in class/function description the same "doc snippet" already used for (2) and (3).
Is this possible?
If so, what's the best practice?
Note: I could get the effect using a separate file for each "doc snippet" and then #includeing it in the right places, but that would defeat the whole purpose that's keep Requirements/Specification/code together while separating them in different sections in the resulting documentation.
Update: following #albert comment I tried the following:
in a standard Doxygen comment I added markers:
/**
* Initialization function.
*
* [AM_init]
* It needs to do a long series of tests to ensure AM can actually work.
*
* It should also allocate all dynamic memory needed to avoid runtime failures.
*
...
* It will be responsibility of system-level daemon to take appropriate action.
* [AM_init]
*
*
* #param ip_addr
* #param port
* #return
*/
static uint32_t AM_init(const char* ip_addr, uint16_t port) {
...
in the "front matter" definition I have (among other things):
/**
#page __init Initialization
#snippet{doc} CommandHandler.c AM_init
*/
The function documentation is rendered correctly (i.e.: the markers are removed)
OTOH the initialization page is "somewhat incomplete":
Initialization
It needs to do a long series of tests to ensure AM can actually work.
that's it.
Apparently the tag is found, but only the first line is actually included.
Further Update: Following #albert answer (accepted) I had success, but the following caveats:
Included snippet ([AM_init]) must be in a standard comment, not a doxygen one, otherwise snippet ends up included twice.
Included snippet must not have leading * (very common in "standard comments".
Included comments should have HTML controls (e.g.: <br/> for line termination) because Markdown constructs ("double newline", in the above case) are notrecognized.
In retrospect I think "Note" in Doxygen \snippet['{'option'}'] <file-name> ( block_id ) documentation addresses, more or less all the above, but I find it very cryptic and I would never have understood the implications without my nose being rubbed into them.
The last one is very annoying because I use a lot Lists and Tables and while HTML syntax is much more powerful, it is also much more difficult to write and to read in sources.
Finding a way to lift this limitation would be "very nice".
With the following code and the current doxygen version (1.9.4 (5d15657a55555e6181a7830a5c723af75e7577e2)) but also with the 1.9.1 (ef9b20ac7f8a8621fcfc299f8bd0b80422390f4b) version, I get good result:
bb.h
/// \file
/**
#page __init Initialization
#snippet{doc} CommandHandler.c AM_init
*/
CommandHandler.c
/// \file
/**
* Initialization function.
*/
/* [AM_init]
It needs to do a long series of tests to ensure AM can actually work.<br>
It should also allocate all dynamic memory needed to avoid runtime failures.<br>
It will be responsibility of system-level daemon to take appropriate action.<br>
[AM_init]
*/
/**
* \snippet{doc} this AM_init
*
* #param ip_addr
* #param port
* #return
*/
static uint32_t AM_init(const char* ip_addr, uint16_t port){}
Doxyfile
EXTRACT_STATIC = YES
EXAMPLE_PATH = .
QUIET = YES
Note: OP rightfully mentioned in further update that there are some things to take care of:
Included snippet ([AM_init]) must be in a standard comment, not a doxygen one, otherwise snippet ends up included twice.
Included snippet must not have leading * (very common in "standard comments".
Included comments should have HTML controls (e.g.: for line termination) because Markdown constructs ("double newline", in the above case) are not recognized.
I'm using JSDoc tutorials, as described in http://usejsdoc.org/about-tutorials.html
I can't get the configuration options to work, and I haven't yet found any examples or discussion of the topic online.
In my trivial example, I pass a tutorials parameter to JSDoc, and it builds a tutorial file for tutorial1.md. I would like to give this tutorial a display name of "First Tutorial".
Following this from the online docs:
Each tutorial file can have additional .js/.json file (with same name, just different extension) which will hold additional tutorial configuration. Two fields are supported:
title overrides display name for tutorial with the one specified in it's value (default title for tutorial is it's filename).
children which holds list of sub-tutorials identifiers.
I tried several attempts at adding tutorial1.json, or tutorial1.js but either JSDoc pukes on the json file, or doesn't seem to recognize anything I throw at it in the js file.
Can anyone suggest a simple format for a tutorial configuration file that should work?
(Edited to include one .js file I tried, which did not change the tutorial display name.)
tutorial1.md
First Tutorial
================
tutorial1.js
/**
#title First Tutorial
*/
#title = "First Tutorial";
title = "First Tutorial";
It works with .json extension but not with a .js extension. jsdoc does not seem to try to even read the file if a .js extension is used. So the doc seems incorrect.
With a .json extension, and using jsdoc 3.2.2, the following works:
{
"title": "Custom Title"
}
Your .json file needs to be in the same directory as your .md file and have the same name (ignoring extensions).
When I compiled my iPhone app with Xcode 4.6, I see a strange error code:
"duplicate symbols for architecture i386".
I know this issue about duplication of file name or class name. so I tried to find the file by using the search bar in Finder. I also tried to search for duplicated classes with the search bar in Xcode, however I could't find it. I already checked that I'm not importing .m files.
What should I do next? please give any advice.
I could resolve this issue myself.
I declare in the header file.
NSString * const FormatTypeTime = #"~~~~~";
I should declare
static NSString * const FormatTypeTime = #"~~~~~";
I forgot to use "static". and I used this variable in the lots of file. that's the reason why every files looked like duplicated.
Thank for answering my question!
This error occurs when a file with same name gets compiled twice.
Go to Project Target-> Build Phases->Look for multiple occurrences of same file under "Compile Sources". You can search for file name there as well.
Remove multiple occurrences from there.
If file is added multiple times in your project then remove duplicate files & keep only one.
The error shows that in any 2 of your files a variable name( or method name ) are duplicated which have global scope. You can solve this by,
*)Renaming the variable or method
OR
*)Change the scope of variable or method to local ( By adding the declaration statement to interface section of .m file. )
after building a web app, I tried out the jsdoc-toolkit. In a config file I added my index.html to the list of source files and also used the x-parameter to make the toolkit aware of the html file.
java -jar jsrun.jar app\run.js -t=templates\jsdoc -x=html,js -c=conf\my.conf
While the doc is generated without any errors, it still ignores any jsdoc annotation I made within the index file.
And when I check the generated doc, the index.html file is listed as source file.
Very simple documentations such as
/**
* testing the doc
* #constructor
*/
function Test(){
}
are simply ignored
Probably because its embedded in tags.
Do you have any idea how to force jsdoc to use this code as well?
Cheers,
zbug
I have a view based iPhone project which performs some animations & suchlike, Seperately I have a C based command line tool project which I use to do some calculations.
I want to integrate the two, so that I can call my C based calculations function at a certain point in my original iPhone project.
The command line tool project is in the form of 2 files, calculations.pch & calculations.m.
I tried to add a new file to my original class & simply copy in the 2 new files (& importing calculations.pch in the View Controller) but upon building I get the error:
Command /Developer/Platforms/iPhoneSimulator.platform/Developer/usr/bin/gcc-4.2 failed with exit code 1
Any suggestions? thanks in advance!
The .pch is quite sparse & looks like this:
//
// Prefix header for all source files of the 'Tester' target in the 'Tester' project.
//
#ifdef __OBJC__
#import <Foundation/Foundation.h>
#endif
Simply remove the .pch file from your project, as the same .pch is already compiled with an iPhone project by default. If that fails, you can always just copy-paste your functions into a new file in your iPhone project.