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.
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 have a list of adjectives (found here), that I would like to be the basis for a "random_adjective(category)" method.
I'm really just taking a stab at this, as my first real attempt at a useful program.
Step 1: Open file, remove formatting. No problem.
list=File.read('adjectivelist')
list.gsub(/\n/, " ")
The next step is to break the string up by category..
list.split(" ")
Now I have an array of every word in the file. Neat. The ones with a tilde before them represent the category names.
Now I would like to break up this LARGE array into several smaller ones, based on category.
I need help with the syntax here, although the pseudocode for this would be something like
Scan the array for an element which begins with a tilde.
Now create a new array based on the name of that element sans the tilde, and ALSO place this "category name" into the "categories" array. Now pull all the elements from the main array, and pop them into the sub-array, until you meet another tilde. Then repeat the process until there are no more elements in the array.
Finally I would pull a random word from the category named in the parameter. If there was no category name matching the parameter, it would return false and exit (this is simply in case I want to add more categories later.)
Tips would be appreciated
You may want to go back and split first time around like this:
categories = list.split(" ~")
Then each list item will start with the category name. This will save you having to go back through your data structure as you suggest. Consider that a tip: sometimes it's better to re-think the start of a coding problem than to head inexorably forwards
The structure you are reaching towards is probably a Hash, where the keys are category names, and the values are arrays of all the matching adjectives. It might look like this:
{
'category' => [ 'word1', 'word2', 'word3' ]
}
So you might do this:
words_in_category = Hash.new
categories.each do |category_string|
cat_name, *words = category_string.split(" ")
words_in_category[cat_name] = words
end
Finally, to pick a random element from an array, Ruby provides a very useful method sample, so you can just do this
words_in_category[ chosen_category ].sample
. . . assuming chosen_category contains the string name of an actual category. I'll leave it to you to figure out how to put this all together and handle errors, bad input etc
Use slice_before:
categories = list.split(" ").slice_before(/~\w+/)
This will create an sub array for each word starting with ~, containing all words before the next matching word.
If this file format is your original and you have freedom to change it, then I recommend you save the data as yaml or json format and read it when needed. There are libraries to do this. That is all. No worry about the mess. Don't spend time reinventing the wheel.
I've been playing around with a .lua file which passes a random phrase using the following line:
SendChatMessage(GetRandomArgument("text1", "text2", "text3", "text4"), "RAID")
My problem is that I have a lot of phrases and the one line of code is very long indeed.
Is there a way to hold
text1
text2
text3
text3
in a list somewhere else in the code (or externally) and call a random value from the main code. Would make maintaining the list of text options easier.
For lists up to a few hundred elements, then the following will work:
messages = {
"text1",
"text2",
"text3",
"text4",
-- ...
}
SendChatMessage(GetRandomArgument(unpack(messages)), "RAID")
For longer lists, you would be well served to replace GetRandomArgument with GetRandomElement that would take a single table as its argument and return a random entry from the table.
Edit: Olle's answer shows one way that something like GetRandomElement might be implemented. But it used table.getn on every call which is deprecated in Lua 5.1, and its replacement (table.maxn) has a runtime cost proportional to the number of elements in the table.
The function table.maxn is only required if the table in use might have missing elements in its array part. However, in this case of a list of items to choose among, there is likely to be no reason to need to allow holes in the list. If you need to edit the list at run time, you can always use table.remove to remove an item since it will also close the gap.
With a guarantee of no gaps in the array of text, then you can implement GetRandomElement like this:
function GetRandomElement(a)
return a[math.random(#a)]
end
So that you send the message like this:
SendChatMessage(GetRandomElement(messages), "RAID")
You want a table to contain your phrases like
phrases = { "tex1", "text2", "text3" }
table.insert(phrases ,"text4") -- alternative syntax
SendChatMessage(phrases[math.random(table.getn(phrases))], "RAID")
Note: getn gets the size of the table; math.random gets a random number (with a max of the size of the phrases table) and the phrases[] syntax returns the table element at the index inside [].