Documentation Wording Help

DavidZemon

I have two functions available in my `BlockStorage` interface - one that returns the size of a block in a block storage device, and one that returns log_2(block size) for said storage device. I've tried to document these two functions, but I feel I've done a poor job wording it. Anyone care to chime in with their opinion of how it should be worded?

/**
 * @brief   Return the size of a sector (also known as a "block") for the given storage device
 *
 * @return  Bytes in a single sector
 */
virtual uint16_t get_sector_size () const = 0;

/**
 * @brief   Determine the number of shifts required to multiply or divide a number by the sector size
 *
 * Because the Propeller does not have a hardware multiply/divide instruction, having log_2(`SECTOR_SIZE`)
 * can be helpful when you need to multiply or divide a number the sector size. Simply invoke this function and
 * then shift left or right by the return value.
 *
 * @return  log_2(`SECTOR_SIZE`)
 */
virtual uint8_t get_sector_size_shift () const = 0;

jmg

Giving a typical example for each can help understanding, and giving range limits is also informative.
If the limit is simply set by the number of VAR bits, give that.
(I'd guess get_sector_size_shift has a limit below 255 )

DavidZemon

Interesting points about specifying the size. Hadn't thought of doing that here.

The limit is set by the specification of the storage device being implemented. I suppose, since my sector size is stored in a 16-bit variable, it would be limited to 15 in reality though. But also - it's a hard-coded value, never changing during runtime. I feel like if I give it a range, the reader might get confused and think that it changes at runtime.