beeware / beeware/rubicon-objc

Needs documentation on how to pass an pointer-to-pointer “out parameter”

Open
#3 1 comment 2 reactions 0 assignees View on GitHub
documentation enhancement
Dominant language
Python
Stars
301
Forks
70
Avg merge
1d 8h
Merged PRs (30d)
18

Description

It is common in Cocoa API for a method to have an “out parameter”, e.g. an `NSError **` parameter that is used to return an error when a call fails.

Taking the deserialisation method in `NSJSONSerialization` for example, this method

``` objc
+ (id)JSONObjectWithData:(NSData *)data
options:(NSJSONReadingOptions)opt
error:(NSError **)error
```

can be called like this in Objective-C:

``` objc
NSError *err = nil;
id obj = [NSJSONSerialization JSONObjectWithData:data options:0 error:&err];
```

And the equivalent with Rubicon-objc would be

``` python
from ctypes import byref, c_void_p

err = c_void_p(0)
obj = NSJSONSerialization.JSONObjectWithData_options_error_(
data, 0, byref(err),
)
```

NB: `err = None` will not work since `byref` expects a ctypes instance, and does not automatically convert `None` to a NULL pointer.

Contributor guide

Open the contributing guide

Research direction

Start with the Objective-C and Rubicon-objc examples in the issue, then locate the project's documentation entry point for API usage guidance. Add a clear explanation of pointer-to-pointer out parameters, the ctypes byref pattern, and why None does not work; done means a newcomer can follow the example successfully.

Written by the indexing model from the issue text.

Assessment

Tech stack
objective-c, python
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.