How to hide certain Objective-C method header documentation (HeaderDoc) comments - objective-c

Is there a way in Objective-C documentation (HeaderDoc) to hide certain comments from being visible to the public?
In other words, when you option-click (alt-click) on a method you're calling, that box pops up showing the comments for that method...I want a certain comment on the method to not show up in that box.
Here's my scenario:
/**
* This method does something.
*
* For more info on why NS_SWIFT_NAME is specified on this, see: <link here>
*/
- (void)doSomething NS_SWIFT_NAME(doSomething())
Now, when someone uses doSomthing() in Swift and looks at the documentation popup box, the comment about NS_SWIFT_NAME makes no sense to them (it has no useful API information for them on how the method works or how to use it). So, I don't want that comment to show up.
However, if someone were to look at the actual method and see NS_SWIFT_NAME on there, I want them to be able to know why it's there. And I don't want to pull the comment outside of the documentation block and make it a // code comment because I think that would be pretty ugly.
Are there any keywords that let you hide certain comments in the header docs? Like #hide or something?

Related

How do you know what methods to use for a task?

I am learning Objective-C Cocoa programming for OS X, and object-based programming in general, so I am a big novice here, so my question is a bit general and my guess is the answer to this is simply "experience"; however, I am curious if there is some route of knowledge to understanding what methods in various classes are best or perhaps required for getting tasks done.
For example, in a programming guide I am instructed to create a document-based program, and the document class contains an array to store data, with the following method bound to a button to create a new entry in the array:
- (IBAction)insertItem:(id)sender {
if (!theItems) {
theItems = [NSMutableArray array];
}
[theItems addObject:#"Double-click to edit."];
[theTableView reloadData];
[self updateChangeCount:NSChangeDone];
}
The array is "theItems" and its data is being presented in a TableView object. I understand that the steps here add a new string to the array and then refresh the table to display it, followed by setting the document to be set to an unsaved state.
What I am not getting is how one would know these specific steps and methods are required. Intuitively it seems one would just add items to the array, and that would be all that's required to have the new values simply show up in the table view for which the array is the data source, so how would one know that the tableView would need to be refreshed with the "reloadData" call? I can see someone (myself) figuring it out by trial and error, but is there some quick resource or guide (ie, some quick flow-chart) either in XCode or elsewhere that indicates for a table view that this would have to be a required action to display the new entry?
If I look at Apple's NSTableView class reference, it claims in the overview that you "modify the values in the data source and allow the changes to be reflected in the table view" which suggest the view is updated automatically, so the requirement to call "reloadData" on the view seems a little obscure.
Look for the guides. In the online class reference for NSTableView, there's a section at the top called "Companion Guides". For NSTableView, it lists the Table View Programming Guide for Mac. (In the prerelease 10.10 docs, the guides are listed under Related Documentation in the left-hand sidebar.)
I could have sworn this same information was available in Xcode's Documentation window, albeit somewhat hidden behind a "More related items" pseudo-link, but when I check right now there's no link to the guide anywhere in the NSTableView class reference. Which is a terrible oversight.
You can also browse or search the Guides section of the developer library.
Familiarity, studying the documentation and possibly reading some good books is the answer. For example, in the docs you quoted (emphasis mine)
you should modify the values in the data source and allow the changes to be reflected in the table view
You should do both these things. If you want it to happen "automatically", look into bindings, which uses several other Cocoa features you won't understand at this point either to do the table data source stuff for you. I'd recommend understanding what is happening manually before handing over control to bindings, so you have some chance of understanding when things go wrong.
As well as looking at the table view documentation, you also need to study the cell, delegate and datasource references. All of those objects work together to give you the functioning table view.

NSDocument - how to prevent a document from being marked as updated automatically?

I have a cocoa app that allows the user to enter a query. I'm using an NSWebView with a TextArea HTML object. The problem is, as soon as I type anything into the textarea, my document gets marked as updated. Does anyone know of a way to prevent this?
I've verified that using a NSTextField does not reproduce this behaviour, but I specifically want to go with the HTML/TextArea for styling.
So basically: Can I make it so an NSDocument does not get marked as edited unless I manually call:
[document updateChangeCount: NSChangeDone];
This post on the Apple mailing list seems to match your problem exactly.
The solution suggested is to set a custom undo manager to the webview (sounds like hard work), however a quick-and-dirty hack looks to me like subclassing updateChangeCount and perverting things to your way of thinking.

Simplest possible way to show two items NSTableView from code?

How I can create a code in XCode 4.2.1 what will create NSTableView and add just couple of items to it?
All what I wanted to do is:
1) Window where is NSTableView
2) I have an array of strings in NSArray which I like to show in that NSTableView
3) All of this should be done in code. So I don't want to learn how to add this action happen when you press button (I know already how to do actions when user click buttons etc), I just want that application launch -> draws the table where is those items from my array. That's it, nothing more.
And yeah I have understood that I do not add items to NSTableView directly. That is not the point in this question. I just mean that I want to show couple of items in that table but I have no and kind of clue WHERE I should add my data from my array.
I have tried to google for example pages for hours (just too many and have not find help) but I will always be stucked in the part when
a) I must do something in the Interface Builder and the images of the interface builder are from version 2.x or 3.x and I have 4.2.1 and it is totally different (new to XCode...). Surely I have drawn my TableView element to UI but I mean delegations etc. Are those necessary at all? Can those be made from source code?
b) Code just does not work anymore because language (Cocoa or Objective-C, I don't know) has changed and I don't know how and what I have to do to make it work on newest version of XCode.
c) There is too much different ways told: "use binding", "you must create new class what is NSTableViewDataSource" etc. I have no any kind of clue what is preferred way, is another way optional or it is "you should use this because another is going deprecated soon" or something.
So please, can somebody give help in step-by-step what I exactly have to do? Should I create some bindings? If so, how and where? Do I have to create DataSource component myself? Are those ways valid any more? If I have to, how I can create it? Create a new class and implement it as a NSTableViewDataSource and then use it? Is that way valid any more and if it is, can sombody show code what is as simple as possible?
I have also checked Apple Documentation page many many times, checked those example codes but there is just too much totally unrelated stuff that I just don't understand at this point so they are totally useless (I mean, I don't know what is required for this task, what are not etc.
I would be very happy if somebody can help short tutorial step-by-step what to do. I mean "step-by-step" like:
1) Create new project
2) Draw NSTableView in project
3) Create new class with this name
4) Write this code: blah blah blah
5) Create another class with this name
6) Write this code
7) Run and see those items from array in NSTableView using (bindings/datasource/whatever is preferred).
Thanks :)
Your tableview needs a datasource. Your datasource is a custom class, it implements the "NSTableViewDataSource" protocol. This protocol contains a few methods that you can use to tell the tableview what data you got.
this includes the objectValue ( the value of the NSCell that is displaying your data on the specified row, and a method that returns the amount of rows the tableview has ( the amount of items in your array ).
Here a tutorial I found by googling:
CocoaDev.com NSTableView tutorial
You can also implement the NSTableViewDelegate protocol which allows some greater control. Like what rows you can select, or some extra configuring of a custom tableview cell.
I must say that back in the day when I started developing desktop applications ( only had experience with web technologies ) that this design pattern confused me as well. Hope you will get your mind round it soon.

How to fix "Protocol Not Implemented"

When I make a new controller called TestController, I insert
<UITableViewDelegate,UITableViewDataSource,UITextFieldDelegate,UISearchBarDelegate>
to the interface of Test.h
When I run the app on the simulator, there are many issues that say
"incomplete implementation" and "method in protocol not implemented"
I know some method is not implemented, but which one? How do I know what method I should add?
Show the issues navigator and expand one of the "method in protocol not implemented" issues. The first detail item will show you where the method is defined in the headers (and, thus, which #protocol it's in). Even better, though, the second detail will show you the name of the protocol.
Switch to the Issues navigator. Ignore the Incomplete implementation message, and look at the Method in protocol not implemented message. You can expand this message to get more information that the compiler provided. The first detail is what you're looking for:
You can see here that I've forgotten to include a method for tableView:numberOfRowsInSection:. I can copy this declaration and paste it into my own code to start writing the method.
Note that there are three issues in my issue navigator. The third is another missing method, which can also be expanded and copied in the same way.
There are two things I can think of which you can look for. First, look in your .h file and see if you have any method prototypes that you may have forgotten to implement, or else implemented and then changed the implementation such that it no longer matched the prototype's method signature.
Second, if the compiler isn't telling you which methods are missing, look at the documentation of UITableViewDelegate, UITableViewDataSource, etc. In the Tasks section, where it lists the various public class and instance methods, it will say "required method" next to any that need to be there. For example, if you class conforms to the UITableViewDataSource delegate protocol, -tableView:cellForRowAtIndexPath: and -tableView:numberOfRowsInSection: are required.
Check your projectname-Prefix.pch file. I got carried away there and imported something I shouldn't have, and that made it look like the one protocol I was implementing in that class was not implemented, when in fact it was. Just go ahead and make sure you aren't including any protocols there.
In my case it was because the file I shouldn't have imported was another protocol file, that was not directly related to the class where I was getting the warning.
Also when you clean out your *-Prefix.pch file, make sure you close and re-open Xcode. I had to do that to get it to take.
Hope this helps!!
Check your implementation file to see if you have included the there. If you have that bit, you need to delete it.

How To CustomToken - Cocoa with Objective-C or MacRuby

I try to build an Input which is able to show one or more Token at the beginning of line.
You can see an example what I'm trying to receive in the image below. (screenshot shows google-macsearch)
http://www.freeimagehosting.net/uploads/4a268855a0.jpg
Cocoa provides the NSToken class, but I like to do it by myself and custom, but I don't know what or how to do.
I tempt to draw the Token. This works fine, but now its on my View and without any functionality. I expect i shout place it somehow into the TextView.
I hope you will give me a hint.
Salut
This is what the NSTokenField class is for. Basically, the token field asks its delegate for information about its tokens, and then draws the tokens itself.
There is a sample, a little tweak can help in your way.
SSToken - A custom NSTokenField
Download the sample, you will find a class called SSToken. Include the class in your project.
Since SSToken is built on composition with NSTextField and interface is similar like NSTokenField, it would be easier for you to customise the tokens and show it in the way you wanted.
It also grows vertically on adding new tokens like in native Mail App.