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\}.
Related
I have two actions:
/**
* #Rest\Get("/items/{itemId}")
*/
public function getAction(UuidInterface $id): View
And
/**
* #Rest\Get("/items/available")
*/
public function getAvailableAction() : View
The thing is that when I'm trying to call getAvailableAction by a link items/available, the getAction is being called. I guess it interprets the word available as an {itemId} somewhy.
How should I solve it?
You guessed right. Just define a proper requirement:
/**
* #Rest\Get("/items/{itemId}", requirements={"itemId" = "\d+"})
*/
If your itemId is an UUID, change the number regex from \d+ to [a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12} or a simplified [a-fA-F0-9\-]{36}.
Don't forget to clear the cache.
I have been struggling with getting the below code excerpt's documentation appear properly with doxygen.
I have searched online for the problem; yet, it seems that the documentation not showing up is mostly due to the member function/variable being private. Even though I seem to be documenting a public member function, which is also non-static, I can't get doxygen working properly. I would appreciate any help of yours.
/**
* #brief Algorithm abstraction.
*
* #tparam float_t `float` or `double`.
* #tparam int_t `int64_t` or similar.
* #tparam StepPolicy Policy for selecting a step-size.
* #tparam OraclePolicy Policy for getting first-order information.
*/
template <class float_t, class int_t, template <class, class> class StepPolicy,
template <class, class> class OraclePolicy>
struct Algorithm : public StepPolicy<float_t, int_t>,
public OraclePolicy<float_t, int_t> {
/**
* #brief Default constructor.
*
*/
Algorithm() = default;
/**
* #brief Constructor with a step-size.
*
* #param[in] step Non-negative step-size value.
*/
Algorithm(float_t step) : StepPolicy<float_t, int_t>{step} {}
/**
* #brief Set the initial step-size of the algorithm.
*
* #param[in] step Non-negative step-size value.
*/
void set_stepsize(float_t step) { StepPolicy<float_t, int_t>::set(step); }
/**
* #brief Get the current step-size of the algorithm.
*
* This does *not* change the state of StepPolicy.
*
* #return float_t Current step-size.
*/
float_t get_stepsize() const { return StepPolicy<float_t, int_t>::get(); }
/**
* #brief Get current step-size based on the algorithm's state.
*
* #param[in] k Current iteration count.
* #param[in] N Dimension of `x` and `dx`.
* #param[in] x Current decision vector.
* #param[in] dx Current first-order information.
* #return float_t Current step-size.
*/
float_t get_stepsize(const int_t k, const int_t N, const float_t *x,
const float_t *dx) {
return StepPolicy<float_t, int_t>::get(k, N, x, dx);
}
private:
int_t k{0};
};
I am not sure if doxygen has anything to do with valid code excerpts, but the above code does indeed compile. Does it have anything to do with templates and inheritance? Am I missing something? I mean, for non-inheriting template classes, doxygen can do its job.
By the way, I do not have any concrete StepPolicy or OraclePolicy somewhere in my directories. Moreover, I can see the constructors getting documented properly. I am just stuck.
I can share my Doxygen file here, which is basically just the defaults overridden in MathJax-related settings.
Thank you, in advance, for your time.
Starting with v1.8.14, there is no such a problem. Apparently, the question was a bug, which has been fixed by the maintainers of doxygen.
Assuming I have a typedef type in a js module
// somewhere/foo.js
/**
* #module
*/
/**
* #typedef Foo
* #type {object}
* property {string} bar - some property
*/
Is it possible to reference this type in another module, so that in the HTML page generated by jsdoc, the type is displayed as a link to the typedef-ed module ?
I tried variations of this, but nothing seems to work...
// somewhere_else/bar.js
/**
* #module
*/
/**
* #param {somewhere/foo/Foo} foo - some param
*/
export default function doStuff(foo) {
...
}
This works for me ...
// somewhere/foo.js
/**
* #module foo
*/
/**
* #typedef module:foo.Foo
* #type {object}
* #property {string} bar - some property
*/
and ...
// somewhere_else/bar.js
/// <reference path="foo.js" />
/**
* #module bar
*/
/**
* #param {module:foo.Foo} foo - some param
*/
function doStuff(foo) {
//...
};
The above answer shows up high in search results so I'm documenting what worked for me in case it helps someone in a similar situation.
I'm using Visual Studio code for a node project with // #ts-check on all my modules. Using the above syntax hiccups on the module: syntax. Also, the code assistance doesn't work properly. It took me a while but the answer ended up being quite simple
If I have the typedef myTypedef in a module myModule then in the second module where I require myModule
mm = require(myModule)
I can use something like
/** #param {mm.myTypedef} myParamName */
The module syntax is not supported by TypeScript so if you're getting here assuming it to work, I haven't been able to get the solutions above to work.
To get it working with TypeScript use Import Types
For the OP the way I would do it is
// foo.d.ts
export type Foo = {
/**
* some property
*/
bar: string,
};
Then refer to it in the JS module as
/**
* #typedef { import("./foo").Foo } Foo
*/
/**
* #param {Foo} foo - some param
*/
export default function doStuff(foo) {
...
}
You can verify things are working on an individual file more strictly by adding the following to the beginning of the file. This will enable typescript checking in Visual Studio code for the specific file to help prepare your move to Typescript in the future.
// #ts-check
Many libraries export types from their root file, to access those in typedefs, change your import to use the import * as format.
For example:
import * as testingLibrary from '#testing-library/react';
/**
* #returns {testingLibrary.RenderResult}
*/
export function myCustomRender() { }
I've tried both of the above approaches.
Firstly, in the case of #typedef module:foo.Foo, VSCode treated the usage of Foo within the same file as any. Which I didn't find acceptable.
Secondly, when using ES6 imports the following issue emerges:
import foo from 'foo'
/** #param {foo.Foo} a - Error Foo does not exist on foo */
On the other hand VSCode recognizes import { Foo } from 'foo' without even using the JSDoc module syntax:
/**
* #module bar
*/
What's more I was also able to reference a property on the imported type, namely:
import { Foo } from 'foo'
/** #param {Foo['bar']} bar */
Note
This project uses Babel and assume compiling code which uses type imports in not feasible without a transpiler.
I'm working with vscode-powertools script which provides access to vscode module at runtime (as opposed to it being available to VSCode at edit time via the local node_modules).
If I would try to import the types with the usual jsdoc import
//#ts-check
/** #typedef {import('c:/Users/USERNAME/.vscode/extensions/ego-digital.vscode-powertools-0.64.0/node_modules/vscode').TextEditor} TextEditor */
I would be getting the File is not a module error:
File 'C:/Users/USERNAME/.vscode/extensions/ego-digital.vscode-powertools-0.64.0/node_modules/vscode/vscode.d.ts' is not a module. ts(2306)
So here's the trick I'm using to typecheck that kind of script:
//#ts-check
/// <reference types="c:/Users/USERNAME/.vscode/extensions/ego-digital.vscode-powertools-0.64.0/node_modules/vscode" />
// Allows us to reference the `vscode` module with jsdoc `#type`
async function vscodeⁱ() {if (1 == 1) return null; return import ('vscode')}
exports.execute = async (args) => {
// Allows us to reference the `vscode` module with jsdoc `#type`
const vscode = await vscodeⁱ()
/** #type {vscode} */
const vs = args.require ('vscode')
// NB: The following code is fully typed in VSCode
const windowᵛ = vs.window
const editorᵛ = windowᵛ.activeTextEditor
const start = editorᵛ.selection.start
}
After many days of frustrating experimenting with jsDoc, it seems that documenting of require-js modules (AMD) has its problems. To start with:
you can't tag your module as class:
define([
"dcl/dcl",
], function (dcl) {
/**
* #class BaseClass
* See {#tutorial getting-started}
*/
var BaseClass = dcl(null,{
foo:function(a){}
});
return BaseClass;
});
jsDoc will not output foo at all! Only by changing it to
/** #module BaseClass */
define([
"dcl/dcl",
], function (dcl) {
/**
* #class module:BaseClass
*/
var BaseClass = dcl(null,{
foo:function(a){}
});
return BaseClass;
});
will enumerate foo as function in the docs. At least something but the trouble doesn't seem to end when it comes to modules. When looking at the jsdoc documentation (pretty poor), it treats Modules different; especially when it comes to constants and enums(link-able):
/** #module BaseClass */
define([
"dcl/dcl",
], function (dcl) {
/**
* #class module:BaseClass
*/
var BaseClass = dcl(null,{
/**
*
* #constant {String} module:BaseClass.COLLAPSED
* #static
* #member
* #name module:BaseClass.COLLAPSED
* */
COLLAPSED : '__wcDockerCollapsedPanel',
/**
* Add a new docked panel to the docker instance.<br>
* <b>Note:</b> It is best to use {#link wcDocker.COLLAPSED} after you have added your other docked panels, as it may ensure proper placement.
* #param {module:BaseClass.COLLAPSED} [targetPanel] - A target panel to dock relative to, or use {#link wcDocker.BaseClass} to collapse it to the side or bottom.
* #returns {wcPanel|Boolean} - The newly created panel object, or false if no panel was created.
*/
addPanel: function (targetPaneloptions) {}
});
return BaseClass;
});
Only by adding EVERYWHERE the module: prefix, your constants and enums become link-able. This looks pretty bad in the documentation. Also, I can't seem to define constants and enums in another module and link to them, memberOf doesn't help either.
So the question is: how to use jsDoc with AMD/Require-JS Modules, or how can I can make jsDoc treating AMD modules(created by var module =...) as classes?
ps: is it possible that its just buggy or not really working? Because I really tried all sorts of tags and combinations but no....Nothing really works as described in the docs.
Anyhow, any thought or links to examples are welcome.
g
I struggled with this same issue and finally came upon #lends
For you example I think all you have to change is
var BaseClass = dcl(null,{
to
var BaseClass = dcl(null, /** #lends BaseClass.prototype */{
Failure to include .prototype will result in jsdoc that defines the object literal members as static. I see you've explicitly defined COLLAPSED as static but not your method, so I'm unclear which you need or if dcl auto-detects constants and functions.
*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!