Since Objective-C I'm a fan of #pragma MARK: but recently I've seen /// -Tag: in Apple's source code. Also noteworthy, it's highlighted in white, while MARK isn't. Tag on the other side does not add any text to the Xcode 'outline' view.
Can anyone explain what the purpose of Tag is?
The - Tag: annotation is used to locate specific places of your own code. You can include it as part of symbols documentation in Swift. E.g. you may add a Tag marker in some Swift file next to a function:
/// - Tag: myFunction
func myFunction() {
print("My function is called")
}
In another file you can refer to this exact place in the code as part of another Swift entity documentation:
/// Uses [myFunction](x-source-tag://myFunction) internally
func anotherFunction() {
myFunction()
}
When using the Quick Help popover on anotherFunction in Xcode, you get an interactive reference (under myFunction text), which takes you to the file (and line) where the /// - Tag: myFunction is located:
I haven't been able to find anything specific to the Tag documentation keyword. It appears to be a custom documentation keyword, though it doesn't appear in Quick Help as expected...
I'm guessing that it may just be a way to allow searching for related code... Maybe it'll come up as a new feature in the future - used to apply "tags" to specific symbols, as you would in Finder, say. That seems reasonable, given that the function referenced in the question is related to custom clustering (see Decluttering a Map with MapKit Annotation Clustering), and the documentation line says /// - Tag: CustomCluster.
When you write a function, you can document the details of that function in Swift using a version of "markdown". See the Markup Formatting Reference and CommonMark for examples.
This documentation appears in the Quick Help popover box, as shown in the question, and in the Quick Help Inspector - displayed in the right-hand panel when your cursor is in a symbol (function name, for example), and you click the question mark in a circle at the top of the inspector panel.
Many pre-defined keywords exist for this documentation, such as - Parameters:, - Returns:, and - Throws:. And, you can also use your own custom keywords. Usually the custom keywords appear in the Quick Help as well, but this - Tag: keyword doesn't seem to do anything (at least in Xcode 9.4.1).
Here's an example of how to use Swift Documentation Markup:
/// Errors associated with String processing.
enum StringError: Error {
case cantCapitalizeAnEmptyString
}
/// Capitalizes a String item.
/// - Tag: I don't know what this is - it doesn't show in Quick Help.
/// - Parameter string: A String item to be capitalized.
/// - Throws `StringError.cantCapitalizeEmptyString` when provided String item is empty.
/// - Returns: The provided String item converted to all capital letters.
/// - Blah: A custom keyword I made up.
func capitalize(string: String) throws -> String {
if string.isEmpty {
throw StringError.cantCapitalizeAnEmptyString
}
return string.capitalized
}
Then, in the Quick Help Inspector, you'll see:
Or, of course, option-clicking the function name will display the Quick Help popover:
As noted in the question, the - Tag: keyword doesn't display anything in either the Quick Help Inspector or the Quick Help popover.
Related
Is it possible to show the documentation of a function in the documentation of another function residing in a different file? Macros are only valid in their own file.
In the Flutter source code, they use something like this, but it does not seem to have any effect:
/// {#macro flutter.widgets.editableText.keyboardType}
Macro docs is what you are looking for. They are already explained here but in summary allows you do exactly what you want: copy a documentation from a place to somewhere else without re-write.
The best you can do is link to the referenced function.
file_a.dart
/// Also see [functionB].
void functionA() {}
file_b.dart
/// Another function.
void functionB() {}
https://dart.dev/guides/language/language-tour#documentation-comments
why
-(void)addSimpleListener:(id<XXSimpleListener>)listener
convert to swift look like this:
func add(_ listener: XXSimpleListener?) {
}
but change the method to this
-(void)addSimpleListener:(id<XXSimpleListening>)listener
and it will convert to this
func addSimpleListener(_ listener: XXSimpleListening?){
}
Xcode (or whatever tool you are using to do the conversion) is merely following Swift API guidelines. Specifically:
Omit needless words. Every word in a name should convey salient information at the use site.
More words may be needed to clarify intent or disambiguate meaning, but those that are redundant with information the reader already possesses should be omitted. In particular, omit words that merely repeat type information.
In the first case, the words SimpleListener in addSimpleListener is repeating the type of the parameter, so they are removed from the method name. However, in the second case, SimpleListener and SimpleListening does not look the same to whatever tool you are using, so it thinks that SimpleListener should be kept.
In my (human) opinion though, I think the method should be named addListener, because:
Occasionally, repeating type information is necessary to avoid ambiguity, but in general it is better to use a word that describes a parameter’s role rather than its type.
Listener is the role of the parameter.
Seems a simple task but despite google and looking at all the menus I cannot find how to look at documentation of classes or objects in XNA.
In unity you just press ctrl and ' what is is in visual c#/XNA? I am looking for information on created classes/Objects not the online documentation/Help.
You can search the MSDN for the required information. For example, here is a link for the SpriteBatch class.
The MSDN is not just limited to XNA, it is a useful tool for all Microsoft based languages.
Please note that some of the XNA documentation is not very informative. I've come across pages on XNA functionality that contain only one or two lines - no example code either!
What about classes that people have created and documented?
The author of the code will need to provide documentation in the code. Here is an example:
/// <summary>
/// This is an example of XML documentation for a class.
/// </summary>
class Program
{
/// <summary>
/// This is an example of XML documentation for a public method.
/// </summary>
/// <param name="name">The name we are validating.</param>
/// <returns>True if valid, otherwise false.</returns>
public bool IsValid(string name)
{
return true;
}
}
Visual Studio will automatically generate most of the XML for you. Just type "///" above the class/method to begin. You can read more on it here.
You will now be able to view the code documentation by hovering over the class/function name.
To anyone who might get this problem in the future - I have solved it.
The files are .chm files and are located in the folder of the classes when available.
Another issue when you are downloading them from another computer to be aware of is they are sometimes blocked.
If that is the case - right click them/properties/general and in the lower right corner there is a button (Unblock) click this, reload the .chm file and all should be readable.
So glad I found this I was starting to question my sanity and it appeared no one else was aware of them or at least understood my problem.
I have a JavaFX GUI in an fxml file with its controller class defined. I have two text items that I want in that GUI, one tied to a variable whose value does not change until the user reloads the screen, the other I would think needs to be a StringProperty as it shows the running total of a column in my TableView. Because of what they are, I'm trying to use Label instead of a TextField as their display control.
I liked Sebastian's answer to this problem here:
Displaying changing values in JavaFx Label
however, when I try to use it I get a compile error that says:
cannot find symbol
symbol: variable textProperty
location: variable salesNoLabel of type Label
I'm not sure what I'm doing wrong, but to start with, my label text is initially set in the fxml file, so in my controller I just have its fx:id substituted for "myLabel" listed in Sebastian's answer:
salesNoLabel.textProperty.bind(sn);
where salesNoLabel is the fx:id of the label and sn is a string variable.
Not sure if you need to see more of my code to help me with this problem, but thanks in advance for checking it out.
Sebastian's answer had a syntax error, I edited it to fix it.
You need to invoke the textProperty() method on the label:
salesNoLabel.textProperty().bind(sn);
Note the addition of parentheses after the textProperty identifier to invoke the method.
If I understand MODX Revolution correctly, I should be able to make a Property Set (Tools -> Property Sets) and apply it to an element as default properties. See rtfm.modx.com.
I have created a Property Set - 'tvsEnabled' - with the following values:
includeTVs: 1
tvPrefix: (empty string)
processTVs: 1
And then I call the following Snippet:
[[getResources#tvsEnabled? &parents=`8` &tpl=`TplArticle`]]
This returns nothing...
Firstly, please provide the code for TplArticle tpl, as there may be error in that tpl as well. The above code is perfectly correct.
Secondly, the tvPrefix parameter should be set properly. If you put an empty string, its no harm. But, try not overriding its default value. Now, if you have put an empty string, your tpl should access template variables according to the tvPrefix that you have provided, for e.g., [[+name]]. If you don't override its default value, you have to access template variables with the +tv. prefix, for e.g., [[+tv.name]].
If this doesn't work out, please do elaborate on the total task at hand and all the pieces of codes in relation to that, which you have written.