Since it seems such a common task, it is hard for me to believe that if I want to add all the doxygen comments in a header file to a group, that I have to do
foo.h
/**
*\addtogroup fooGroup
* #{
*/
...
...
...
/**#}*/
Is there a way to make this work without the #{ comment?
The short answer is no. An alternative is using the #ingroup command. If you put that command right below the #file command, then the file reference is added to the group, e.g.:
foo.h:
/**
* #file foo.h
* #ingroup fooGroup
*/
...
This also requires that you have defined a group with that name (could be also in a different file):
/**
* #defgroup fooGroup Foo
* #brief A brief description of the Foo component.
* #details A more detailed description of the Foo component.
*/
BUT the big disadvantage is that you have to put the #ingroup command for each entity that you want to display in the group documentation. This means you have to add the command to each declaration or definition, like enums, structs, variables and functions.
Using the #addtogroup and the #{ ... #} commands have the big advantage that you don't need to add each entitity to the group using the #ingroup command.
The sense of groups is to collect documentation from different files under one specific name. You could also divide one file into different groups, so the #{ and #} comments are defining the beginning and the end of a region which shall be added to a group name.
Another reason is that groups may build hierarchies, e.g. one file with the following code:
/**
* #addtogroup group_name
* #{
*/
<Code Example 1>
/**
* #}
*/
/**
* #addtogroup group_name_2
* #{
*/
<Code Example 2>
/**
* #addtogroup sub_group_name
* #{
*/
<Code Example 3>
/**
* #addtogroup sub_sub_group_name
* #{
*/
<Code Example 4>
/**
* #}
*/
/**
* #}
*/
/**
* #}
*/
This would result in the following group hierarchy:
group_name
group_name_2
sub_group_name
sub_sub_group_name
The only thing you might try is to add an Alias for the \addtogroup and { command, like:
ALIAS += "begingroup{1} = \addtogroup \1 \{"
But in this case you would still have to add the #} command at the end of the file.
Related
I am trying to document C interface of my library with doxygen. All functions are grouped within a virtual classes and the assigned with operator \memberof. Since there are a lot of functions, I would like to assign multiple functions with group operator #{.
/**
* \class Base
*/
/**
* \class Derived
* \extends Base
*/
/**
* \memberof Base
* #{
*/
/**
* \brief Function A
*/
void Base_A();
/**
* \brief Function B
*/
void Base_B();
/** #} */
This creates page for derived class as following:
For some reason, there are two sections for inherited members - public inherited and related. In my opinion, both functions should be in the same category.
Adding \memberof command to every single function seems to solve the problem.
/**
* \class Base
*/
/**
* \class Derived
* \extends Base
*/
/**
* \brief Function A
* \memberof Base
*/
void Base_A();
/**
* \brief Function B
* \memberof Base
*/
void Base_B();
Can someone confirm this being a bug?
Can someone provide a working group assignment of multiple functions to a class? I have hundreds of functions and adding so many commands is not viable.
I hesitate to call this a bug. The \{ \} commands are intended to be used for grouping together with grouping commands like \ingroup, \defgroup, \addtogroup, \weakgroup and in this case it is used together with \memberof.
It sees the \memberof command and 'assigns' the next function to 'Base' conform:
This command makes a function a member of a class in a similar way as \relates does, only with this command the
function is represented as a real member of the class. This can be useful when the programming language does
not support the concept of member functions natively (e.g. C).
It looks like it ignores the \{ and\}.
Consider automatically generated comments at the begining of a model:
/**
* User.js
*
* #description :: TODO: You might write a short summary of how this model works and what it represents here.
* #docs :: http://sailsjs.org/documentation/concepts/models-and-orm/models
*/
What does # sign state for in #description and #docs lines?
I think the # just represents an entity. See JSdoc standard
I understand that we can use \defgroup key word to define a group in doxygen and add the class in this group by using key word \addtogroup. My question is how can I refer to this group in the documentation. For example,
/**
* \defgroup abc abc
*/
/**
* \addtogroup auxiliary_functions
* #{
*/
/**
* Introduction to A.
*/
class A
{
};
/*
* #}
*/
Then, in a page section, how can refer abc group?
/** #page tttt
* how to refer to group abc?
*
*/
You can reference any group by using its label. In your case, to reference the abc group from page ttt use the following
/** #page tttt
*
* For more information, please see #ref abc
*/
The resulting page will contain a link to your group, the text of which will reflect the group's title (abc in your case).
As far as I know by using the keyword ingroup
/**
* \ingroup abc
* \brief Explain why
*/
extern int VarInA;
You can find more here: Grouping doc
I'm brand new to JSDoc, and I'm trying to figure out the best way to tag my code. For some reason after I label something as a #class, I can't get anything to appear as #inner:
/**
* The logger, to simply output logs to the console (or potentially a variable)
* #class Logger
* #requires 'config/globalConfig'
*/
define(["config/globalConfig"], function (config) {
/**
* Instantiate a new copy of the logger for a class/object
* #constructor
* #param name {string} - The name of the class instantiating the logger
*/
return function (name) {
/**
* #memberOf Logger
* #type {string}
*/
this.name = name;
/**
* Place the message on the console, only for "DEV" level debugging
* #function
* #memberOf Logger
* #param message {string}
*/
this.debug = function (message) {
... some code ...
};
};
});
Right now all the members are appearing as <static>. If I add the #inner tag to any of the attributes/functions they vanish completely from the output.
Edit: I also forgot to mention. The #constructor flag doesn't seem to be working either. If I remove that entire section, it appears the same in the output. The output does not include the #param that I would like to mention with my constructor.
Please let me know if this is completely off, I'm just kind of guessing here since the JSDoc3 documentation is a bit difficult to read.
So I figured it out, still not sure if it's absolutely correct. I had to use "Logger~name" to have it appear correctly as an inner function. According to the JSDoc documentation, this ~ is "rarely used". Seems to be the only thing that works for me.
define(["config/globalConfig"], function (config) {
/**
* The logger, to simply output logs to the console (or potentially a variable)
* #class Logger
* #param name {string} - The name of the class instantiating the logger
*/
return function (name) {
this.name = name;
/**
* Place the message on the console, only for "DEV" level debugging
* #function Logger~debug
* #param message {string}
*/
this.debug = function (message) {
... code ...
};
};
});
*How to Document following function in JSDoc JS-Toolkit *
I want to document try and help method in this main function
but i did not figure it out how to do that.
/** Sample doc
* #class
* #constructor
* #name Sample
*/
var main=function(){
this.value="";
/** help function
* #param {String} Name
*/
this.help=function(name){
console.log('help me'+name);
}
/** help function
* #param {String} Name
*/
this.try=function(name){
console.log('try me'+name);
}
}
I just struggled with this for several hours. I tried:
#member
#augments
#method
#this
From the examples and tutorials I found, member functions and variables should appear in the output simply by having /** description/* comments above them, but I found that was not the case. Like you, I'm using standard JavaScript constructors, where this should be able to be inferred automatically due to the #constructor being in place. Maybe there's some wrinkle I'm not seeing.
In the end, I found two tags that worked for me, #name and#memberof. They both allow you to specify the object that the property is a member of. Using #name in this way is undocumented (at least, I didn't see it anywhere), but very straightforward. You'll also need to use #function.
Here's an example with the #name tag:
/** help function
* #name Sample.try
* #function
* #param {String} Name
*/
this.try=function(name){
console.log('try me'+name);
};
And here's an example with the #memberof tag:
/** help function
* #memberof Sample
* #function
* #param {String} Name
*/
this.try=function(name){
console.log('try me'+name);
};
As you can see the output is almost the same. The only difference that I see is that #memberof includes this. in the method name. For that reason I've settled on using #name.
The remaining issue is that the functions are per-instance, not <static>.
Hope this helps!