Platform API "Reference" is broken

Brief version:

API reference MUST use canonical prototypes/declarations.

Long version:

Actual platform API reference is awful. It's hard reading even for programmers, what makes you think that it would be good for beginners ?

Let's keep pretty weak structure for other discussion (fortunately, it could be overriden with site search). Real problem is functions/methods articles.

Arguments ? Default values ? Overloaded versions ? Return values ? You need to read whole article to bring them together. But some aspects even missed. For example, what the actual type of Stream::readStringUntil() return value ? (i.e. how could I get it know from article)

Why don't you use canonical prototypes or even Doxygen, instead of re-inventing your own wheels ?

Kind regards.

Could you provide an example of an existing piece of of the reference, and how it would look if re-written in the way that you'd like ?

I've certainly seen doxygen-based iso-9000 process-conformant "references" that I find a lot less useful than the Arduino reference. People seem to think they're DONE after writing one-line descriptions of their functions' arguments and return values, without providing nearly enough explanation or "context." (Let's see. What do I have handy... This will do...

 * @brief Initializes the UART mode according to the specified parameters in
 *        the UART_InitTypeDef and create the associated handle.
 * @param huart: Pointer to a UART_HandleTypeDef structure that contains
 *               the configuration information for the specified UART module.
 * @retval HAL status
HAL_StatusTypeDef HAL_UART_Init(UART_HandleTypeDef *huart)

and that's from a vendor-provided, licensed, library... Awful!)

In my opinion, actual reference needs addition, in form of canonical prototypes. Prototypes would:

  • prevent reference lacks (like String reference in Stream::readString() !)
  • show parent class, argument and return types, default values, etc. in single place (for me, actual “fragmented” description is uncomfortable)
  • allow simple switching between related types and methods articles

for example:

String Serial::readString()

for overloaded methods it could be more complicated, but IMHO not less important:

size_t Serial::print ()
size_t Serial::print (, )

in particular:

size_t print (char val)
size_t print (const String & val)
size_t print (const char * val)
size_t print (const Printable & val)
size_t print (const __FlashStringHelper * val)

size_t print (unsigned char val, int format=DEC)
size_t print (int val, int format=DEC)
size_t print (unsigned int val, int format=DEC)
size_t print (long val, int format=DEC)
size_t print (unsigned long val, int format=DEC)
size_t print (double val, int format=2)

Something like that or another …

That, of course, could be achieved another way, than prototypes …