Updating the API Documentation

Software Resources
1

Hello World!

My name is Connor, and I’m helping update some of the Blinks API documentation so new developers can have a reference when learning! That being said, everyone here on the forums knows the struggle of trying to learn a brand new API, and I’m sure there are plenty of suggestions that you have. I’ve gotten a version of the new API at this link, and I would greatly appreciate some feedback!

6 Likes
2

Looking really good! I really like the format you went with, and it’s great to have the annotated examples and links to practical examples, both here on the forums and in the games themselves! I do have a couple of suggestions:

  • I’m not sure if this was just a temporary placeholder, but your “Defined Colors” links go to a google doc. I think you can instead just link to the “Defined Colors” section you already have in the doc using the address https://github.com/cmwolf19/Blinks-SDK-Docs-EN/blob/master/docs/api.md#defined-colors

  • One thing I struggled with when learning to work with graphics was remembering the positions of the hue color wheel when using makeColorHSB(). I’m not sure if this would be possible or how much work would be involved, but it might be nice to have an image, or a link to a reference of that full wheel, so developers could get a better idea of where certain values fall on the color spectrum. (I know you can do the math to figure it out, but this is just for convenience).

  • Another thing I struggled with when I was starting off was understanding how the “setValueSent” methods worked - I wasn’t aware that the value you indicate is sent many times per second rather than just once every time the method was called. It might be worthwhile to touch on that behavior somewhere in the notes for these methods.

I don’t have enough time at the moment to go through the API more thoroughly (I’ll keep reading it over the course of the next day or two), but so far it’s looking like a really handy guide, especially for new devs. Thanks for putting in the work to revamp this!

4 Likes
3

I noticed there are no mentions of datagrams whatsoever. If you ever write a section about those, I have several suggestions. :stuck_out_tongue: :slight_smile:

2 Likes