organize the growing list of class members

[2bndy5]

I think we should organize the class docs better somehow because there are so many functions. I’ll have to think about how to categorize them…

Originally posted by @TMRh20 in https://github.com/nRF24/RF24/issue/812#issuecomment-985542406

[2bndy5]

Organizing the class docs for sphinx is a little easier in docs/sphinx/classRF24.rst than it is in doxygen markup (within src comments). Below is a experimental grouping based on radio's features (while still retaining the traditional Basic/Advanced/Configurable API sections).

The section's headers are ordered like so:

• ~~~~~~~~~ This header is used as the page's title
  • ========= This a page's section
    • ************** This is a section's subsection

RF24 class
~~~~~~~~~~

.. cpp:class:: RF24

    .. doxygenfunction:: RF24::RF24 (uint16_t,uint16_t,uint32_t)
    .. doxygenfunction:: RF24::begin (void)
    .. doxygenfunction:: RF24::begin (_SPI *spiBus)

Dynamically Instantiated Pins
=============================

.. doxygenfunction:: RF24::RF24 (uint32_t _spi_speed=RF24_SPI_SPEED)
.. doxygenfunction:: RF24::begin (uint16_t _cepin, uint16_t _cspin)
.. doxygenfunction:: RF24::begin (_SPI *spiBus, uint16_t _cepin, uint16_t _cspin)

Basic API
============

.. doxygenfunction:: RF24::startListening
.. doxygenfunction:: RF24::stopListening
.. doxygenfunction:: RF24::available (void)
.. doxygenfunction:: RF24::available (uint8_t *pipe_num)
.. doxygenfunction:: RF24::read
.. doxygenfunction:: RF24::write (const void *buf, uint8_t len)
.. doxygenfunction:: RF24::openWritingPipe (const uint8_t *address)
.. doxygenfunction:: RF24::openWritingPipe (uint64_t address)
.. doxygenfunction:: RF24::openReadingPipe (uint8_t number, const uint8_t *address)
.. doxygenfunction:: RF24::openReadingPipe (uint8_t number, uint64_t address)
.. doxygenfunction:: RF24::closeReadingPipe

Advanced API
============

.. doxygenfunction:: RF24::isChipConnected
.. doxygenfunction:: RF24::isValid
.. doxygenfunction:: RF24::isPVariant
.. doxygenfunction:: RF24::whatHappened

Debugging helpers
*******************

.. doxygenvariable:: RF24::failureDetected
.. doxygenfunction:: RF24::printDetails
.. doxygenfunction:: RF24::printPrettyDetails
.. doxygenfunction:: RF24::getARC

Advanced Transmission
*********************

.. doxygenfunction:: RF24::write (const void *buf, uint8_t len, const bool multicast)
.. doxygenfunction:: RF24::writeAckPayload
.. doxygenfunction:: RF24::writeFast (const void *buf, uint8_t len)
.. doxygenfunction:: RF24::writeFast (const void *buf, uint8_t len, const bool multicast)
.. doxygenfunction:: RF24::reUseTX
.. doxygenfunction:: RF24::writeBlocking
.. doxygenfunction:: RF24::startFastWrite
.. doxygenfunction:: RF24::startWrite
.. doxygenfunction:: RF24::txStandBy()
.. doxygenfunction:: RF24::txStandBy (uint32_t timeout, bool startTx=0)

Power Management
****************

.. doxygenfunction:: RF24::powerDown
.. doxygenfunction:: RF24::powerUp

FIFO Management
***************

.. doxygenfunction:: RF24::rxFifoFull
.. doxygenfunction:: RF24::flush_tx
.. doxygenfunction:: RF24::flush_rx

Ambiguous Signal Detection
**************************

.. doxygenfunction:: RF24::startConstCarrier
.. doxygenfunction:: RF24::stopConstCarrier
.. doxygenfunction:: RF24::testCarrier
.. doxygenfunction:: RF24::testRPD

Configuration API
==================

.. doxygenfunction:: RF24::setAddressWidth
.. doxygenfunction:: RF24::setRetries
.. doxygenfunction:: RF24::maskIRQ
.. doxygenfunction:: RF24::toggleAllPipes

Channel (Frequency)
*******************

.. doxygenfunction:: RF24::setChannel
.. doxygenfunction:: RF24::getChannel

Dynamic Delays
**************
.. doxygenvariable:: RF24::txDelay
.. doxygenvariable:: RF24::csDelay

Payload Sizes
*************

.. doxygenfunction:: RF24::setPayloadSize
.. doxygenfunction:: RF24::getPayloadSize
.. doxygenfunction:: RF24::enableDynamicPayloads
.. doxygenfunction:: RF24::disableDynamicPayloads
.. doxygenfunction:: RF24::getDynamicPayloadSize

Auto-Acknowledgement
********************

.. doxygenfunction:: RF24::setAutoAck (bool enable)
.. doxygenfunction:: RF24::setAutoAck (uint8_t pipe, bool enable)
.. doxygenfunction:: RF24::enableAckPayload
.. doxygenfunction:: RF24::disableAckPayload
.. doxygenfunction:: RF24::enableDynamicAck
.. doxygenfunction:: RF24::isAckPayloadAvailable

Radiation Options
*****************

.. doxygenfunction:: RF24::setPALevel
.. doxygenfunction:: RF24::getPALevel
.. doxygenfunction:: RF24::setDataRate
.. doxygenfunction:: RF24::getDataRate
.. doxygenfunction:: RF24::setRadiation

CRC Lengths
***********

.. doxygenfunction:: RF24::setCRCLength
.. doxygenfunction:: RF24::getCRCLength
.. doxygenfunction:: RF24::disableCRC

Protected API
==============

These are the members and functions made available to derivatives that inherit from the RF24 class.

.. doxygenfunction:: RF24::beginTransaction
.. doxygenfunction:: RF24::endTransaction
.. doxygenfunction:: RF24::read_register (uint8_t reg)
.. doxygenfunction:: RF24::read_register (uint8_t reg, uint8_t *buf, uint8_t len)
.. doxygenvariable:: RF24::ack_payloads_enabled
.. doxygenvariable:: RF24::addr_width
.. doxygenvariable:: RF24::dynamic_payloads_enabled

[2bndy5]

For the CirPy lib I ended up separating this page into 3 pages:

1. Basic API
2. Advanced API
3. Configuration API

Although, this lib might also get a Protected API page (similar to its Deprecated API page).

[2bndy5]

We can't nest member groups (@name cmd) in doxygen, but we can put the member groups in "module" groups (@defgroup cmd). This means we can group the class members in a way that will show up in the RF24 class document and also as seperate groups in the "modules" pages (like we are currently doing with the "Porting: xxx" groups).

I also found a way to use a doxygen template to rename and reorder the tabs at the top of the page. The following picture shows that "Modules" tab is renamed to "API Groups" and "Related Pages" tab is renamed to "Support". I then clumped together the "Classes" tab and the "API Groups" tab to be under a user-defined tab called "Reference API". Gleam what you can from this screenshot:

I got distracted and started playing with the CSS to support light and dark themes as specified by the user's OS settings

[TMRh20]

Nice work! It looks like you have all the bases covered so I’m good with these changes. I thought it was a bit too granular at first, but on further review I think you nailed it.

…

On Dec 7, 2021, at 5:22 AM, Brendan ***@***.***> wrote:  We can't nest member groups ***@***.*** cmd) in doxygen, but we can put the member groups in "module" groups ***@***.*** cmd). This means we can group the class members in a way that will show up in the RF24 class document and also as seperate groups in the "modules" pages (like we are currently doing with the "Porting: xxx" groups). I also found a way to use doxygen template to rename and reorder the tabs at the top of the page. The following picture shows that "Modules" tab is renamed to "API Groups" and "Related Pages" tab is renamed to "Support". I then clumped together the "Classes" tab and the "API Groups" tab to be under a user-defined tab called "Reference API". Gleam what you can from this screenshot: I got distracted and started playing with the CSS to support light and dark themes as specified by the user's OS settings — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android.

[2bndy5]

we can group the class members in a way that will show up in the RF24 class document and also as separate groups in the "modules" pages

This turns out to be inaccurate. The functions still show on the class doc's member list, but the member's doc is moved to the corresponding module group page. What may be a little confusing about this idea is that the module group page has its own list of functions which resembles the class' entire list of functions the user clicked on to get to the member's doc. I think I'll need to keep looking for a better solution...

[TMRh20]

I think after a year we should probably accept that it isn't going to get much better. I don't really mind how all the docs are currently, so maybe we should just "leave sleeping dogs lie"?

[2bndy5]

It could be achieved with a different docs generator like sphinx. Doxygen makes some intrusive (and unavoidable) assumptions about how groups are displayed in the output. I have been working on a sphinx extension that uses libclang to parse C/C++ sources into an AST that gets translated to auto-generated API docs. It is slow going as there are a few quirks that have to be ironed out before recommending it for deployment. See current sample output