Objective-C binding organization

[wokalski]

This is a (possibly incomplete) list of rules that I think we should apply to our bindings. All rules should lead to easier navigation and to minimizing the binding surface. Rules which don't serve this purpose... well should not be here. If there's a way to make something better organised but more verbose - I'm all for it but there has to be an automated way to verify if we follow the rule!

• Don't use .h files unless we need to expose a symbol to other callers in the C universe
• Always prefix stubs which are exposed to OCaml using ml_
• Don't prefix stubs with _stubs.(h|c). They are in the stubs directory anyway.
• Name stub files the same as we call corresponding bindings on the OCaml side (makes it much easier to navigate the codebase at the beginning) with "Brisk" prefix.
• On the OCaml side, use separate files for different components. The name should always match the .c file - "Brisk" prefix.
• Put stub files in stubs directory and OCaml bindings in bindings directory
• Avoid adding stuff to BriskCocoa.c.
• Don't create files like Cocoa_helpers_stubs.c. Searching by file name gets confusing. Even if a file is supposed to contain just one binding/function, it's better to name it properly. Like BriskColor.h
• Do not forget to expose new bindings and components in top-level Brisk_macos module (if needed).
• Prefer putting stuff in Objective-C over C. If a function is not exposed to OCaml it's preferable to put it in a category or a Class itself (if it's an internal class to Brisk).

[rauanmayemir]

I think we could use stubs and bindings directories with equally named counterparts for C and OCaml.

[wokalski]

Prefer putting stuff in Objective-C over C. If a function is not exposed to OCaml it's preferable to put it in a category or a Class itself (if it's an internal class to Brisk).

This might raise some eyebrows. In essence I think it's reasonable to still follow Objective-C/OOP conventions in the stubs. So if there's something that you want to get from an instance or you want an instance to do, you call a method on it.

[wokalski]

@rauanmayemir great idea 👍.

[rauanmayemir]

The only thing I feel uneasy about is how to umbrella bindings under the Cocoa module without exposing them in the library root. I don't won't to list all the bindings in the Cocoa and then list all the package modules in Brisk_macos_renderer wrapping module, but maybe we should.

[wokalski]

The top level package (i.e. Brisk_macos_renderer) should have a generic name (like Brisk, which should also include Brisk_Core with applied OutputTree). The top level module will be named the same for all platforms (you will link with a different library depending on the target.) Cocoa module should be used for platform specific stuff. It can also be exposed as part of Brisk package.

[wokalski]

@rauanmayemir if we think the rules are set here we should document it in some contributing document and close the issue.

[rauanmayemir]

We need an imperative component example and couple more complex protocols to flesh out complete-ish bindings guide.

[wokalski]

This issue is about binding organization, not a binding guide so I think we're fine here 😄. We can add more granular issues for other stuff or we'll never close this one.

[wokalski]

Some interesting links:

https://arxiv.org/pdf/1812.04905.pdf
https://github.com/let-def/goo