search

NEEOInc / neeo-sdk

NEEO Brain SDK
https://neeoinc.github.io/neeo-sdk/
MIT License
49 stars 17 forks source link

SDK Documentation #147

Closed tmrobert8 closed 5 years ago

tmrobert8 commented 6 years ago

Someone really needs to go through the SDK documentation and correct it. There are NUMEROUS issues in the documentation and a lot of missing information.

Example:

  1. setType still references ACCESSOIRE even though it lists the valid values of ACCESSORY
  2. addTextLabel - shows the getter as a 'function' and the example shows 'controller.getArtist' - so you have no idea what the function signature is unless you look at the examples (this happens a number of times for various functions).
  3. returns "Function" is almost universally uninformative. Please add notes what the function signature is so I don't have to figure the example (or look at the examples).
  4. Many of the examples are incorrect in the function signatures. Look at addPowerStateSensor as an example - both the setter/getter actually provide a deviceId but the example doesn't show that.
neophob commented 6 years ago

Hi Tim

thanks for the update.

  1. ACCESSOIRE is still present for backwards compatibility, and equal to ACCESSORY

We will check the other points. Do you have more examples for nr. 4?

thanks

tmrobert8 commented 6 years ago
  1. Yes but the description talks about ACCESSOIRE but then the value lists doesn't show it (but shows ACCESSORY). You should update the description to ACCESSORY and in the values say something like 'ACCESSORY (or ACCESSOIRE for backwards compatibility)'
  2. AddSensor, AddSlider, AddSwitch...
pfiaux commented 5 years ago

I think points 3/4 should already be partially improved and can be further improved with the next version of the SDK. Since it's a rewrite in typescript we already added lots of types and we will add more over time (meaning we can define the parameters and return values of a function), in turns we should be able to also generate more precise documentation.

I'll try to take a look at the ACCESSOIRE/ACCESSORY use through out for consistency and the controller.getArtist

pfiaux commented 5 years ago

ACCESSOIRE will no longer be mentioned in the documentation, all the add*() function documentation was revised to include more clear examples (especially function parameters).

This will be included in the next update of the next branch. Thanks @tmrobert8 for the feedback!