Diverse issues with SDK documentation

[Joolee]

1. It's not described anywhere where device icons should be defined
2. The list below "Capability options" is a mess
3. Also, it's not listed whether options are optional or not
4. With composer enabled by default, the capabilities documentation should be updated to reflect that
5. There is a mention of updateCapabilityValue but it's not a function listed in the Device class function list
6. Really missing HTML examples and best-practices in the pairing "custom views" section
7. Also in the custom views section, the distinction between server- and client-side code and functions is really unclear
8. Navigation between views as configured in app.json isn't clearly documented. 'prev' seems to work but is completely undocumented. What other options are there?
9. It's unclear if you can interact with the navigation buttons by en/disabling them or binding input validation functions to them
10. The 'app store' documentation page should be linked from the Driver documentation section (on both the main and images page) and in the "images" property on the app manifest page.
11. It's unclear whether the 'Done' pairing template can be used with custom views and how you should do that. This is the case with most system templates by the way.
12. The example on the app manifest page lists property 'gtin'. That's only documented on the SDK v1 documentation. It's function is unclear
13. The documentation of the 'device' object on the "pairing" and the "custom views" pages are wildly different even though they seem to require the same considerations
14. Examples extensively use callback functions even though the 'best practices' list them as being deprecated in favor of promises

[WeeJeWel]

There are all great points and we'll be sure to address them a.s.a.p.. Thank you!

[Joolee]

https://apps.developer.athom.com/ManagerI18n.html#__ Link isn't formatted properly: "@{link Homey#__}"

[WeeJeWel]

https://apps.developer.athom.com/ManagerI18n.html#__ Link isn't formatted properly: "@{link Homey#__}"

Fixed, sharp!

[Joolee]

In the setViewStoreValue help text, it's described you can set a device for the system view 'add_devices'. That's not described in the help page of that system view however. Are there other hidden options only known to Athom? Homey.setViewStoreValue('add_devices', 'devices', devicesArray);

[WeeJeWel]

In the setViewStoreValue help text, it's described you can set a device for the system view 'add_devices'. That's not described in the help page of that system view however. Are there other hidden options only known to Athom? Homey.setViewStoreValue('add_devices', 'devices', devicesArray);

Would be better to document it there, yes. For now you can find an example here: https://apps.developer.athom.com/tutorial-Drivers-Pairing-Custom%20Views.html

Keep up your great feedback! It's so hard to write great documentation when you're blind because you know your own system too well!

[Joolee]

On the capabilities page, the documentation for registerCapabilityListener doesn't do anything with promises or callbacks. As far as I understand, you need to return whether the action was successful or Homey will assume it wasn't.

[Joolee]

"Flow Editor's sidebar." is mentioned in the Flow → Devices page. We don't have that anymore with the unfortunate migration to mobile-only.

[Joolee]

The compose plugin node-homey uses gives us a lot more options than just the documented $extends. I can see it being used in Athom's own apps and the source at https://github.com/athombv/node-homey/blob/840792bd929bc5cfbb2a12f90c20cdbe09b36f53/lib/AppPluginCompose/index.js leads me to believe the documentation on that subject is far from complete.

[Joolee]

The mandatory "images" section for drivers is not documented anywhere. Also, neat tricks like {{driverAssetsPath}} are not documented.

[Joolee]

Might want to document the hidden feature of the 'SimpleClass' class as used here: https://github.com/athombv/node-homey-rfdriver/blob/62b090922d07808295ee761e528905d932e53776/lib/PairDevice.js#L18

Makes logging much more easy.

[Joolee]

Link to "Device~settingsCallback" is dead on the Device.html page.

[Joolee]

The "duration" parameter for 'dim' and similar capabilities is not documented in the references of those capabilities (see: https://github.com/athombv/node-homey-lib/blob/87c628e7f15ace71731e0b56b469821105efb69c/assets/capability/capabilities/dim.json) or any other location in the docs. There appears to be a reference to them in the ZigBee Meshdriver documentation though... (https://athombv.github.io/node-homey-meshdriver/ZwaveLightDevice.html#ZwaveLightDevice)

[Joolee]

Internationalization: "Possible languages are: en and nl. Support for more languages will be added in the future." Same page says that's not true. Also, README files in other languages are not documented.

[Joolee]

The Flows documentation is full of references to the old web-interface and the "required" option for arguments is not documented at all.

[Joolee]

.homeyignore files are not documented

[Joolee]

Device trigger flow card filters are poorly documented. Missing 'capabilities', 'driver_uri' (why would you use this one?) and the using of pipes (|) as 'or'.

[Joolee]

The fact that /tmp is writable is not documented. Only /userdata is mentioned in the documentation.

[Joolee]

The method for making device specific tokens is not very clear from the docs. The only way I could find to do that is by making a (custom) capability with uiComponents set to null.

The only hint to this in the documentation is "By default a device's capability are registered as global tokens." here

It would be a good idea to amend that section by describing how you would make a device specific token. Also, on the documentation about uiComponent, you could add a small explanation about why you would want to hide the UI. (To make tokens, I guess)

On a related note: Please add unique ID's to all the header elements in the docs to allow making direct links to specific sections :)