In building my documentation I'm running into a lot of warning messages such as the following:
/home/X/Y/src/core/include/math/bigintntl/transformntl.h:92: warning: documented empty return type of NTL::NumberTheoreticTransformNtl::ForwardTransformToBitReverseInPlace. I'd like to turn off the specific warnings related to X is not documented. How might I go about doing so? I'm building the documentation of a rather large library, and until we have time to go back and update the docs, this just adds a lot of noise to our builds.
The documenting line:
/**
* In-place forward transform in the ring Z_q[X]/(X^n+1) with prime q and
* power-of-two n s.t. 2n|q-1. Bit reversing indexes. [Algorithm 1 in
* https://eprint.iacr.org/2016/504.pdf]
*
* #param &rootOfUnityTable is the table with the n-th root of unity powers in
* bit reverse order.
* #param &element[in,out] is the input/output of the transform of type VecType and length n.
* #return none
*/
void ForwardTransformToBitReverseInPlace(
const VecType& rootOfUnityTable, VecType* element);
from OpenFHE library
and the .rst file looks like the following (autodoxygenindex is a Breathe directive: https://breathe.readthedocs.io/en/latest/directives.html#autodoxygenindex):
Core Math Big Int NTL Documentation
=========================================
.. autodoxygenindex::
:project: core_math_bigintntl
while the conf.py file is here.
Looks like the issue for me was that breathe was regenerating the documentation because I was using a specific command. Unfortunately, this regeneration seemed to ignore the Doxyfile that was coming in. So, I had to manually pass in the relevant variables via breathe_doxygen_config_options See breathe config-values
Related
When I define an entity with and provide a documentation for it:
/**
User Info:
* `event` - the corresponding event.
*/
static let eventNotification = Notification.Name(rawValue: "MSGameEvent")
Quick Help displays it wrong:
As you can see, the doc is split into two parts (Summary and Discussion) with the Declaration stuffed in the middle. This makes the documentation barely readable (and hurts my perfectionism).
How can I make the quick help continuous?
I just read source code of libdispatch, but i found there is a word, "voucher", just appear so many times, but i do not know what it is mean actually.
So could any tell me the true means of this word, thank you very much for your great help.
Best Regards
Axis
I just find answer from source code:
/*
* Mach Voucher - an immutable collection of attribute value handles.
*
* The mach voucher is such that it can be passed between processes
* as a Mach port send right (by convention in the mach_msg_header_t’s
* msgh_voucher field).
*
* You may construct a new mach voucher by passing a construction
* recipe to host_create_mach_voucher(). The construction recipe supports
* generic commands for copying, removing, and redeeming attribute value
* handles from previous vouchers, or running attribute-mananger-specific
* commands within the recipe.
*
* Once the set of attribute value handles is constructed and returned,
* that set will not change for the life of the voucher (just because the
* attribute value handle itself doesn't change, the value the handle refers
* to is free to change at will).
*/
Best Regards
Axis
I'm using HeaderDoc to document my code and I would like to link to other methods in the documentation. I'm not trying to generate HTML (at least for now) but I do want it to appear in Xcode's right panel. The following is the documentation for -applicationDidEnterBackground: as it appears in Xcode. I want to achieve those blue links referencing other methods I wrote myself:
The docs say to use #link, but it doesn't seem to work:
Here's what I tried:
/**
* #abstract Returns an array with a copy of all elements in the heap in sorted order.
*
* #discussion The original heap remains unchanged. This getter uses Heap Sort which takes O(n log n),
* although it copies the heap first (in linear time). If losing the elements on the heap is
* acceptable you should use #link -removeAllObjectsWithArray: #/link instead, which is faster.
*/
Here's the result:
As you can see it's not rendering properly. I read here that #link is broken, but the comment dates back to 2013. Is there a fix? Am I doing it wrong?
Edit: I tried Santa's suggestion, this is the result:
/**
* #abstract Whether the heap is empty.
*
* #discussion An empty heap contains no objects, in which case this property returns <code>YES</code>.
* Returns <code>NO</code> otherwise, which also implies that calls to {#link count}
* return zero.
*/
Renders as:
I want to have comments work in the traditional way they do In C in Apple's Xcode. I have installed VVDocumentor and I really like how the default way it comments is, i.e.:
/*
* Comments go here
*/
/*
* multiple
* lined
* comment
*/
I hoped to be able to use CComment, to help me do that, but what it does is just
/* comments go here */
/* multiple
lined
comment*/
Which is ugly. VVDocumentor doesn't help either because if one hits enter the result is
/*
* multiple
* lined
* comment
new comment here
*/
Which is unhelpful.
I'd like to modify Xcode such that the behavior of hitting enter takes this.
/*
* multiple
* lined
* comment
*/
to this
/*
* multiple
* line
* comment
* new comment line here
*/
I'm aware that you can simply block comment, by selecting text and pressing ⌘ + /, but that doesn't achieve what I'm looking for, and more importantly when I'm commenting I must press it again every time I press enter.
I'm sure someone else is looking for this since it's a pretty common style however my google-fu has failed thus far.
I would like to know whether it is possible to define own doxygen comment styles. The usual style is something like this (Javadoc-like):
/**
*
* Descriptions and stuff
*
*/
or (when using Qt):
/*!
*
* Descriptions and stuff
*
*/
I would prefer something like
/*!===============================================================
*
* Descriptions and stuff
*
================================================================*/
But the doxygen parser doesn't allow this syntax. So my questions is, if there is a way to define own comment styles.
I don't think you can define your own comment styles, but with some slight changes to the format, it might match.
See this page on documentation blocks in the Doxygen documentation:
Some people like to make their comment blocks more visible in the documentation. For this purpose you can use the following:
/********************************************//**
* ... text
***********************************************/
(note the 2 slashes to end the normal comment block and start a special comment block).
or
/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////