How can we document objects in Firmware?

[dmiddlecamp]

I was trying to use WiFi.scan -- and it mentions "WiFiAccessPoint", but that object and its properties aren't in our documentation anywhere. I can grep our firmware to find the answer, but this seems like maybe something that could be in a reference document somewhere?

[monkbroc]

We can just make a section like the one for CANMessage.

Do you feel up for it?

[technobly]

Sometimes objects are really large... and it feels wrong to add them to the documentation copy/paste wise. Julien's example is very succinct so it looks great, but other's might now be so appealing. I've often wanted a CODE FOLDING container for docs... so we can keep the readability, but if a user wants to dive in they can unfold the section and drill into the details.

As for WiFiAccessPoint... here's what you'd have to include I think. It's getting to be kind of longish but not too bad.

typedef enum {
    WLAN_SEC_UNSEC = 0,
    WLAN_SEC_WEP,
    WLAN_SEC_WPA,
    WLAN_SEC_WPA2,
    WLAN_SEC_NOT_SET = 0xFF
} WLanSecurityType;

typedef enum {
    WLAN_CIPHER_NOT_SET = 0,
    WLAN_CIPHER_AES = 1,
    WLAN_CIPHER_TKIP = 2,
    WLAN_CIPHER_AES_TKIP = 3
} WLanSecurityCipher;

typedef struct WiFiAccessPoint {
   size_t size;
   char ssid[33];
   uint8_t ssidLength;
   uint8_t bssid[6];
   WLanSecurityType security;
   WLanSecurityCipher cipher;
   uint8_t channel;
   int maxDataRate;   // mdr in bits/s
   int rssi;        // when scanning
} WiFiAccessPoint;

[monkbroc]

I plan on adding auto-generated documentation from the firmware source code.