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:
Related
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
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 have multiple todo items I want to add for a function.
What is the correct way to add them in a phpDoc comment block?
I understand that I should use the #todo tag.
But I am unsure of whether I should use a single #todo tag per item, or one #todo tag for the whole list.
Zero or more #todo tags is valid.
PSR-5: PHPDoc
Syntax
#todo [description]
Example
/**
* Counts the number of items in the provided array.
*
* #todo add an array parameter to count
*
* #return int Returns the number of elements.
*/
function count()
{
<...>
}
From the standard (emphasis mine):
The #todo tag is used to indicate that an activity surrounding the associated "Structural Elements" must still occur. Each [#todo] tag MUST be accompanied by a description that communicates the intent of the original author; this could however be as short as providing an issue number.
The way I read this paragraph, there may be multiple #todo tags (since the standard refers to "each" instead of "the" tag) and each tag represents a single incomplete behavior (since it reads "an activity", instead of "activities").
This, to me, makes the most sense, as each #todo acts as an item in an overall check list. As you complete an item, you "check it off" by deleting the todo item. This would appear very clearly as a line delete in your version control diffs.
However, these are simply annotations, so you may choose of course to ram multiple tasks into one.
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 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.