Can we get a feedback section for the developer documentation similar to what Microsoft has in order to help improve it?

Question

Hi guys,

I have an enhancement requestion that I think would help a lot of developers, especially those new to Swift.

The current developer documentation is awfully sparse on details, code examples, and a lot of the time the syntax shown is very confusing. I think it would be helpful if Apple did what Microsoft does and have a "feedback" section at the bottom of their documentation pages that people can offer suggestions about.

Take for example the page on addTarget, it lists it's declaration as this:

func addTarget(_ target: Any?, action: Selector, for controlEvents: UIControlEvents)

Yet to get it to work, you have to do this:

func addTarget( self, action: #selector(myFunctionToCall), for .touchUpInside)

To me this seems like an error in the documentation since not only is there no mention of #selector (Selector looks like a type in the defintion) but also the controlEvents parameter is completely dropped, despite there being no _ infront of it, making it inconsistent with other code.

There's no code snippet on this page either to see an example of how to use it, it's just expected that people know it.

I think allowing people to provide feedback for individual pages would be very useful and would help get Apples documentation up to speed. I hate to say it but Microsoft does an excellent job with their documents. There are code snippets, examples, and information galore for every class.

Forums Feedback

256

Posted by

SN81

Reply

Add a Comment

Answer 1

You are confusing the declaration (what is shown in the docs) with the call (what is in your code). For each parameter, the declaration shows the argument label (if different than the parameter name) followed by a spce, the parameter name followed by a colon, and the type ot the parameter. When you call the function, if an argument label is in the declaration, you type the argument label (unless _ is specified in the declaration) followed by a colon, then the actual parameter you want to pass. If no argument label is given, you type the parameter name followed by a colon, then the actual parameter you want to pass. In your example #selector is how you create a variable of type Selector, and .touchUpInside a case of the UIControlEvents enumeration type. If an argument label is given in the declaration, the parameter name is not used when you call the function; it is used by the code inside the function when it wants to access the parameter. If you write your own functions and you specify both an argument label and a parameter name, your code inside the function would need to use the parameter name. See "Function Argument Labels and Parameter Names" here for the full explanation in the Swift 3 manual.

You are correct, though, that some of the documentation (especially the newer Swift versions of things) has very little information.

EDIT: Added "If an argument label is given in the declaration, " to the start of the 5th sentence.

EDIT 2: Clarified a few things.

Posted by

guywithmazda

Add a Comment

Answer 2

BTW to file an official enhancement request, use the bug reporter (Report Bugs link at bottom right of forum pages). When you create a bug report, you can choose Enhancement Request as one of the options. You can file bug reports and enhancement requests against the documentation.

Posted by

guywithmazda

Add a Comment

Can we get a feedback section for the developer documentation similar to what Microsoft has in order to help improve it?

Replies