Native Extensions Guide is lacking about Singleton extensions

[jtara]

The documentation on native extensions is lacking in the discussion of Singleton vs Factory objects.

The section purports to take a "deeper look into the two approaches".

http://docs.rhomobile.com/en/5.0.25/guide/native_extensions#a-deeper-look-into-the-two-approaches-to-developing-extensions-singleton-and-factory

However, it only takes any kind of look into Factory.

Basically, it tell you if you want Factory, don't change anything.

No clue, really, on how to change it to a Singleton.

It is implied that to make a Singleton, you might remove <DEFAULT_INSTANCE/> template.

It doesn't state that you should add <SINGLETON_INSTANCES/> (I think misspelled with a plural, but now we have to live with that!)

It is also implied that you would remove the enumerate method, since for Factory you "keep it".

No, I do not know what each piece of the puzzle means, because the documentation has made it into a puzzle!

There is seemingly an example of a Singleton extension here:

https://github.com/sharn722/rhomobile_instagram/blob/master/instagram/ext/instagram.xml

It seems the developer was equally-confused, though, because Factory stuff left laying-around.

Scroll down to the Templates section, and again the same thing happens. It describes only DEFAULT_INSTANCE, doesn't say a think about creating a Singleton.

There is this somewhat-promising link:

https://github.com/rhomobile/rhodes/tree/master/res/generators/templates/api/xml_templates

... which suggests perhaps one ought to avail oneself of the (misspelled) singleton_instances template.

[jtara]

OK, upon some reflection (and finally getting something working...) the description here is basically accurate, but very confusing! It really could use some expanded coverage, with specific examples of implementing

1. simple static methods on a module (what is actually demonstrated in the example, and - I think - incorrectly called "Singleton"
2. a class, with both instance and class methods. This is what the generator creates a framework for. But the Native Extensions Guide has you first rip all that out, and shows how to do (1). It then never goes on to show how to actually implement a full class with instances! The reader is left on their own.
3. a singleton. That is, a real singleton. Basically same as (2) but restricted to only one global instance. It's really just a specialized case of (2). Use case here is you may not know really if you want instances or not, and so you can hedge your bets and write it from the start with instance methods, but then you can change your mind later and allow more than one instance. Same decision you might make in Ruby code.

In fact, it would very helpful to relate each way of writing a native extension API with it's Ruby equivalent!

The various internal Rhodes APIs that have instances let you also access a singleton via methods on the module. So, it would be useful to include an example showing how to do this.

I'd suggest perhaps a separate page on each type of API, since it would be too much to absorb on a single page.

In any case, this needs to be fleshed-out, because it is very difficult to decipher from what is in this documentation!