Adds documentation comments (fixing doxygen warnings).

include/esp8266/sys/select.h

@@ -24,7 +24,7 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  *
- * \file select.h
+ * \file esp8266/sys/select.h
  * This file imlements POSIX select() prototypes.
  *
  * @author Stuart W. Baker

include/freertos/bootloader_hal.h

@@ -42,10 +42,11 @@
 #ifdef __cplusplus
 extern "C" {
 #else
+/// Hack to allow compiling this code in C context too.
 typedef unsigned bool;
 #endif
 
-// Number of 32-bit words in one checksum data.
+/// Number of 32-bit words in one checksum data.
 #define CHECKSUM_COUNT 4
 
 /** Static definitions of the application. These will be flashed with the
@@ -69,6 +70,8 @@ struct app_header {
     uint32_t checksum_post[CHECKSUM_COUNT];
 };
 
+/// Parametrizes the @ref bootloader_led function with logical functions that
+/// can be assigned to physical LEDs.
 enum BootloaderLed {
   /* 1 when there is an incoming packet pending, an outgoing packet pending or
      datagram being transmitted or deceived. */
@@ -88,6 +91,8 @@ enum BootloaderLed {
 /** Write this value to __bootloader_magic_ptr and jump to the bootloader entry
  * point in order to explicitly call the bootloader. */
 static const uint32_t REQUEST_BOOTLOADER = 0x76b89b1eU;
+/// This is the place where @ref REQUEST_BOOTLOADER has to be written before
+/// rebooting the MCU to force entering the bootloader.
 extern uint32_t __bootloader_magic_ptr;
 
 /** Initializes the hardware to a safe state of the outputs. This function may
@@ -113,8 +118,10 @@ extern void application_entry(void);
 /** Resets the microcontroller. Never returns. */
 extern void bootloader_reboot(void);
 
-/** Sets the LEDs indicated by @param mask to the value indicated by @param
- *  value. */
+/** Sets status LEDs.
+ * @param led the logical function describing which LED to set.
+ * @param value is 1 to turn LED on, 0 to turn it off.
+ */
 extern void bootloader_led(enum BootloaderLed led, bool value);
 
 /** Checks if there is an incoming CAN frame from the hardware.
@@ -209,10 +216,12 @@ extern void raw_write_flash(
 extern void checksum_data(const void* data, uint32_t size, uint32_t* checksum);
 
 /** Suggests an NMRAnet CAN alias for use. If the running application has saved
- *  the last used alias, this function returns it. */
+ *  the last used alias, this function returns it. 
+ * @return the suggested alias. */
 extern uint16_t nmranet_alias(void);
 
-/** @returns the NMRAnet NodeID for this hardware node. */
+/** @return the NMRAnet NodeID for this hardware node. 
+ */
 extern uint64_t nmranet_nodeid(void);
 
 #ifdef __cplusplus

include/freertos/can_ioctl.h

@@ -43,6 +43,7 @@ extern "C" {
 /** Magic number for this driver's ioctl calls */
 #define CAN_IOC_MAGIC ('c')
 
+/// ioctl minor type used for the read/write active notifiable integration.
 #define NOTIFIABLE_TYPE 13
 
 /** read active ioctl. Argument is a literal pointer to a Notifiable. */

include/freertos/endian.h

@@ -87,19 +87,31 @@ static inline uint64_t __bswap_64(uint64_t x)
     #define be64toh(x) (x)
     #define le64toh(x) __bswap_64 (x)
 #else
+/// Converts a host endian 16-bit value to big endian.
     #define htobe16(x) __bswap_16 (x)
+/// Converts a host endian 16-bit value to little endian.
     #define htole16(x) (x)
+/// Converts a big endian 16-bit value to host endian.
     #define be16toh(x) __bswap_16 (x)
+/// Converts a little endian 16-bit value to host endian.
     #define le16toh(x) (x)
 
+/// Converts a host endian 32-bit value to big endian.
     #define htobe32(x) __bswap_32 (x)
+/// Converts a host endian 32-bit value to little endian.
     #define htole32(x) (x)
+/// Converts a big endian 32-bit value to host endian.
     #define be32toh(x) __bswap_32 (x)
+/// Converts a little endian 32-bit value to host endian.
     #define le32toh(x) (x)
 
+/// Converts a host endian 64-bit value to big endian.
     #define htobe64(x) __bswap_64 (x)
+/// Converts a host endian 64-bit value to little endian.
     #define htole64(x) (x)
+/// Converts a big endian 64-bit value to host endian.
     #define be64toh(x) __bswap_64 (x)
+/// Converts a little endian 64-bit value to host endian.
     #define le64toh(x) (x)
 #endif
 

include/freertos/fcntl.h

@@ -40,16 +40,21 @@
 extern "C" {
 #endif
 
+/// ioctl parameter space for our custom defined ioctls in the freertos
+/// drivers.
 #define F_FREERTOS_SPECIFIC_BASE 1000
 
+/// ioctl to set the length of the internal fifo buffer.
 #define F_SETPIPE_SZ (F_FREERTOS_SPECIFIC_BASE + 0)
 
 
 #ifndef FREAD
+/// Workaround for missing header defines on some newlib versions.
 #define FREAD 1
 #endif
 
 #ifndef FWRITE
+/// Workaround for missing header defines on some newlib versions.
 #define FWRITE 2
 #endif
 

include/freertos_select/sys/select.h

@@ -24,7 +24,7 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  *
- * \file select.h
+ * \file include/freertos_select/select.h
  * This file imlements POSIX select() prototypes.
  *
  * @author Stuart W. Baker

include/mach/endian.h

@@ -33,17 +33,29 @@
 
 #include <architecture/byte_order.h>
 
+/// Converts a host endian 16-bit value to big endian.
 #define htobe16(x) OSSwapHostToBigInt16(x)
+/// Converts a host endian 16-bit value to little endian.
 #define htole16(x) OSSwapHostToLittleInt16(x)
+/// Converts a big endian 16-bit value to host endian.
 #define be16toh(x) OSSwapBigToHostInt16(x)
+/// Converts a little endian 16-bit value to host endian.
 #define le16toh(x) OSSwapLittleToHostInt16(x)
 
+/// Converts a host endian 32-bit value to big endian.
 #define htobe32(x) OSSwapHostToBigInt32(x)
+/// Converts a host endian 32-bit value to little endian.
 #define htole32(x) OSSwapHostToLittleInt32(x)
+/// Converts a big endian 32-bit value to host endian.
 #define be32toh(x) OSSwapBigToHostInt32(x)
+/// Converts a little endian 32-bit value to host endian.
 #define le32toh(x) OSSwapLittleToHostInt32(x)
 
+/// Converts a host endian 64-bit value to big endian.
 #define htobe64(x) OSSwapHostToBigInt64(x)
+/// Converts a host endian 64-bit value to little endian.
 #define htole64(x) OSSwapHostToLittleInt64(x)
+/// Converts a big endian 64-bit value to host endian.
 #define be64toh(x) OSSwapBigToHostInt64(x)
+/// Converts a little endian 64-bit value to host endian.
 #define le64toh(x) OSSwapLittleToHostInt64(x)

include/nuttx/endian.h

@@ -84,19 +84,31 @@ static inline uint64_t __bswap_64(uint64_t x)
     #define be64toh(x) (x)
     #define le64toh(x) __bswap_64 (x)
 #else
+/// Converts a host endian 16-bit value to big endian.
     #define htobe16(x) __bswap_16 (x)
+/// Converts a host endian 16-bit value to little endian.
     #define htole16(x) (x)
+/// Converts a big endian 16-bit value to host endian.
     #define be16toh(x) __bswap_16 (x)
+/// Converts a little endian 16-bit value to host endian.
     #define le16toh(x) (x)
 
+/// Converts a host endian 32-bit value to big endian.
     #define htobe32(x) __bswap_32 (x)
+/// Converts a host endian 32-bit value to little endian.
     #define htole32(x) (x)
+/// Converts a big endian 32-bit value to host endian.
     #define be32toh(x) __bswap_32 (x)
+/// Converts a little endian 32-bit value to host endian.
     #define le32toh(x) (x)
 
+/// Converts a host endian 64-bit value to big endian.
     #define htobe64(x) __bswap_64 (x)
+/// Converts a host endian 64-bit value to little endian.
     #define htole64(x) (x)
+/// Converts a big endian 64-bit value to host endian.
     #define be64toh(x) __bswap_64 (x)
+/// Converts a little endian 64-bit value to host endian.
     #define le64toh(x) (x)
 #endif
 

include/windows/endian.h

@@ -72,7 +72,9 @@ static inline uint64_t __bswap_64(uint64_t x)
             ((x & 0x00000000000000ffULL) << 56));
 }
 
-#if LITTLEENDIAN
+/// @todo check that the macro tested here is actually defined for the windows
+/// platform.
+#if CONFIG_ENDIAN_BIG
     #define htobe16(x) (x)
     #define htole16(x) __bswap_16 (x)
     #define be16toh(x) (x)
@@ -88,19 +90,31 @@ static inline uint64_t __bswap_64(uint64_t x)
     #define be64toh(x) (x)
     #define le64toh(x) __bswap_64 (x)
 #else
+/// Converts a host endian 16-bit value to big endian.
     #define htobe16(x) __bswap_16 (x)
+/// Converts a host endian 16-bit value to little endian.
     #define htole16(x) (x)
+/// Converts a big endian 16-bit value to host endian.
     #define be16toh(x) __bswap_16 (x)
+/// Converts a little endian 16-bit value to host endian.
     #define le16toh(x) (x)
 
+/// Converts a host endian 32-bit value to big endian.
     #define htobe32(x) __bswap_32 (x)
+/// Converts a host endian 32-bit value to little endian.
     #define htole32(x) (x)
+/// Converts a big endian 32-bit value to host endian.
     #define be32toh(x) __bswap_32 (x)
+/// Converts a little endian 32-bit value to host endian.
     #define le32toh(x) (x)
 
+/// Converts a host endian 64-bit value to big endian.
     #define htobe64(x) __bswap_64 (x)
+/// Converts a host endian 64-bit value to little endian.
     #define htole64(x) (x)
+/// Converts a big endian 64-bit value to host endian.
     #define be64toh(x) __bswap_64 (x)
+/// Converts a little endian 64-bit value to host endian.
     #define le64toh(x) (x)
 #endif
 

src/dcc/Defs.hxx

@@ -24,7 +24,7 @@
  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  * POSSIBILITY OF SUCH DAMAGE.
  *
- * \file Defs.hxx
+ * \file dcc/Defs.hxx
  *
  * Definitions for DCC concepts.
  *
@@ -37,10 +37,15 @@
 
 namespace dcc {
 
+/// Which address type this legacy train node uses. These address types
+/// translate to mutually independent packets on the track.
 enum class TrainAddressType
 {
+    /// DCC packets with short address (1..127)
     DCC_SHORT_ADDRESS,
+    /// DCC packets with long address (128..~10000)
     DCC_LONG_ADDRESS,
+    /// Marklin-motorola packets. Addresses 1..80 are supported.
     MM,
 };
 

src/dcc/LocalTrackIf.hxx

@@ -86,6 +86,10 @@ protected:
     FixedPool pool_;
 };
 
+/// StateFlow that accepts dcc::Packet structures and sends them to a local
+/// device driver for producing the track signal.
+///
+/// The device driver must support the select() model.
 class LocalTrackIfSelect : public LocalTrackIf
 {
 public:

src/dcc/Loco.cxx

@@ -40,6 +40,9 @@
 namespace dcc
 {
 
+/// Forces compilation of all existing train implementations even though many
+/// are actually templates. This avoid needing to put all this code into a .hxx
+/// file.
 extern void createtrains();
 
 template <> DccTrain<Dcc28Payload>::~DccTrain()

src/dcc/Loco.hxx

@@ -44,6 +44,17 @@
 namespace dcc
 {
 
+/// Describes what sort of packet the dcc:PacketSource (usually a single train)
+/// should generate. This is used for two purposes:
+///
+/// - When a user action results in a high priority band packet to be enerated,
+///   we can enqueue a message containing this code to the refreshloop
+///   object. Then when the refresh loop gets to the given packet, the train
+///   will be called with the appropriate code to generate the desired packet
+///   from its internal state (the freshest version of that).
+///
+/// - When a train is on the background refresh loop, it can keep an internal
+///   variable describing what packet to generate next as a refresh packet.
 enum DccTrainUpdateCode
 {
     REFRESH = 0,

src/dcc/Packet.cxx

@@ -32,7 +32,7 @@
  * @date 10 May 2014
  */
 
-#define LOGLEVEL WARNING
+//#define LOGLEVEL WARNING
 
 #include "dcc/Packet.hxx"
 
@@ -257,7 +257,9 @@ void Packet::start_mm_packet()
     header_raw_data = MARKLIN_DEFAULT_CMD;
 }
 
+/// Helper array to translate a marklin address to a bit sequence.
 static const uint8_t marklin_address[3] = {0b00, 0b11, 0b10};
+/// Helper array to translate a marklin function set command to a packet.
 static const uint8_t marklin_fn_bits[5] = {0,          0b01010000, 0b00000100,
                                            0b00010100, 0b01010100};
 

src/dcc/PacketFlowInterface.hxx

@@ -40,6 +40,7 @@
 
 namespace dcc {
 
+/// Interface for flows and ports receiving a sequence of DCC (track) packets.
 typedef FlowInterface<Buffer<dcc::Packet>> PacketFlowInterface;
 
 }  // namespace dcc

src/dcc/PacketSource.hxx

@@ -41,6 +41,7 @@
 namespace dcc {
 
 struct Packet;
+/// C++ type encompassing a speed value for OpenLCB.
 typedef nmranet::SpeedType SpeedType;
 
 /// Abstract class for streams of DCC packets. there will be typically one

src/dcc/RailCom.cxx

@@ -79,6 +79,18 @@ const uint8_t railcom_decode[256] =
        INV,    INV,    INV,    INV,    INV,    INV,    INV,    INV,
 };
 
+/// Helper function to parse a part of a railcom packet.
+///
+/// @param fb_channel Which hardware channel did the railcom message arrive
+/// at. typically from 0.. num channels - 1: for a command station always 0,
+/// for a multi-channel railcom decoder it's as many as the number of ports.
+/// @param railcom_channel 1 or 2 depending on which part of the cutout window
+/// the data is from.
+/// @param ptr raw railcom data read from the UART.
+/// @param size how many bytes were read from the UART
+/// @param output where to put the decoded packets (or GARBAGE packets if
+/// decoding fails).
+///
 void parse_internal(uint8_t fb_channel, uint8_t railcom_channel,
     const uint8_t *ptr, unsigned size,
     std::vector<struct RailcomPacket> *output)

src/dcc/RailCom.hxx

@@ -85,12 +85,22 @@ std::string railcom_debug(const Feedback& fb);
 
 /// Special constant values returned by the @ref railcom_decode[] array.
 namespace RailcomDefs {
+/// invalid value (not conforming to the 4bit weighting requirement)
   static const uint8_t INV = 0xff;
+/// Railcom ACK; the decoder received the message ok. NOTE: some early software
+/// versions may have ACK and NACK exchanged.
   static const uint8_t ACK = 0xfe;
+/// The decoder rejected the packet.
   static const uint8_t NACK = 0xfd;
+/// The decoder is busy; send the packet again. This is typically returned when
+/// a POM CV write is still pending; the caller must re-try sendingthe packet
+/// later.
   static const uint8_t BUSY = 0xfc;
+/// Reserved for future expansion.
   static const uint8_t RESVD1 = 0xfb;
+/// Reserved for future expansion.
   static const uint8_t RESVD2 = 0xfa;
+/// Reserved for future expansion.
   static const uint8_t RESVD3 = 0xf8;
 }