support sublists & sentences splitted into multiple lines

[PingPongun]

(all examples used below taken from NordicSemiconductor Softdevice API)
In doxygen param, retval and other Notation's are allowed to contain sublists eg.

 * @retval ::NRF_ERROR_INVALID_STATE One or more of the following is true:
 *                                   - Invalid Connection State
 *                                   - Notifications and/or indications not enabled in the CCCD
 *                                   - An ATT_MTU exchange is ongoing

currently doxygen-rs parses all lines separately and splits this into:
[in top/function description section ]

///- Invalid Connection State
///- Notifications and/or indications not enabled in the CCCD
///- An ATT_MTU exchange is ongoing

[in return values section]

///* ::NRF_ERROR_INVALID_STATE One or more of the following is true: 

Which produces total mess. After PR this would look like:

///* ::NRF_ERROR_INVALID_STATE One or more of the following is true:
///  * Invalid Connection State
///  * Notifications and/or indications not enabled in the CCCD
///  * An ATT_MTU exchange is ongoing

(all in one section)
Second thing currently not supported by doxygen-rs is line/sentence split into multiple line (probably to force maximum line width). eg.

 * @param[in,out] p_hvx_params Pointer to an HVx parameters structure. If @ref ble_gatts_hvx_params_t::p_data
 *                             contains a non-NULL pointer the attribute value will be updated with the contents
 *                             pointed by it before sending the notification or indication. If the attribute value
 *                             is updated, @ref ble_gatts_hvx_params_t::p_len is updated by the SoftDevice to
 *                             contain the number of actual bytes written, else it will be set to 0.

and one more time doxygen-rs splits this and places it in different sections.
This Pull Request aims to improve behavior in this two cases
(how it works:
it replaces String in bunch of places with NestedString that is able to logicaly represent sublist;
in parser if indentation is detected it is assumed that current line is continuation to previous one
and previous NestedString is modified: either new element is pushed to NestedString.sub(in case of sublist) or line is appended to NestedString.top string(in case of multi line sentence)
)
sample function docs:

doxygen

/**@brief Notify or Indicate an attribute value.
 *
 * @details This function checks for the relevant Client Characteristic Configuration descriptor value to verify that the relevant operation
 *          (notification or indication) has been enabled by the client. It is also able to update the attribute value before issuing the PDU, so that
 *          the application can atomically perform a value update and a server initiated transaction with a single API call.
 *
 * @note    The local attribute value may be updated even if an outgoing packet is not sent to the peer due to an error during execution.
 *          The Attribute Table has been updated if one of the following error codes is returned: @ref NRF_ERROR_INVALID_STATE, @ref NRF_ERROR_BUSY,
 *          @ref NRF_ERROR_FORBIDDEN, @ref BLE_ERROR_GATTS_SYS_ATTR_MISSING and @ref NRF_ERROR_RESOURCES.
 *          The caller can check whether the value has been updated by looking at the contents of *(@ref ble_gatts_hvx_params_t::p_len).
 *
 * @note    Only one indication procedure can be ongoing per connection at a time.
 *          If the application tries to indicate an attribute value while another indication procedure is ongoing,
 *          the function call will return @ref NRF_ERROR_BUSY.
 *          A @ref BLE_GATTS_EVT_HVC event will be issued as soon as the confirmation arrives from the peer.
 *
 * @note    The number of Handle Value Notifications that can be queued is configured by @ref ble_gatts_conn_cfg_t::hvn_tx_queue_size
 *          When the queue is full, the function call will return @ref NRF_ERROR_RESOURCES.
 *          A @ref BLE_GATTS_EVT_HVN_TX_COMPLETE event will be issued as soon as the transmission of the notification is complete.
 *
 * @note    The application can keep track of the available queue element count for notifications by following the procedure below:
 *          - Store initial queue element count in a variable.
 *          - Decrement the variable, which stores the currently available queue element count, by one when a call to this function returns @ref NRF_SUCCESS.
 *          - Increment the variable, which stores the current available queue element count, by the count variable in @ref BLE_GATTS_EVT_HVN_TX_COMPLETE event.
 *
 * @events
 * @event{@ref BLE_GATTS_EVT_HVN_TX_COMPLETE, Notification transmission complete.}
 * @event{@ref BLE_GATTS_EVT_HVC, Confirmation received from the peer.}
 * @endevents
 *
 * @mscs
 * @mmsc{@ref BLE_GATTS_HVX_SYS_ATTRS_MISSING_MSC}
 * @mmsc{@ref BLE_GATTS_HVN_MSC}
 * @mmsc{@ref BLE_GATTS_HVI_MSC}
 * @mmsc{@ref BLE_GATTS_HVX_DISABLED_MSC}
 * @endmscs
 *
 * @param[in] conn_handle      Connection handle.
 * @param[in,out] p_hvx_params Pointer to an HVx parameters structure. If @ref ble_gatts_hvx_params_t::p_data
 *                             contains a non-NULL pointer the attribute value will be updated with the contents
 *                             pointed by it before sending the notification or indication. If the attribute value
 *                             is updated, @ref ble_gatts_hvx_params_t::p_len is updated by the SoftDevice to
 *                             contain the number of actual bytes written, else it will be set to 0.
 *
 * @retval ::NRF_SUCCESS Successfully queued a notification or indication for transmission, and optionally updated the attribute value.
 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
 * @retval ::NRF_ERROR_INVALID_STATE One or more of the following is true:
 *                                   - Invalid Connection State
 *                                   - Notifications and/or indications not enabled in the CCCD
 *                                   - An ATT_MTU exchange is ongoing
 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
 * @retval ::BLE_ERROR_INVALID_ATTR_HANDLE Invalid attribute handle(s) supplied. Only attributes added directly by the application are available to notify and indicate.
 * @retval ::BLE_ERROR_GATTS_INVALID_ATTR_TYPE Invalid attribute type(s) supplied, only characteristic values may be notified and indicated.
 * @retval ::NRF_ERROR_NOT_FOUND Attribute not found.
 * @retval ::NRF_ERROR_FORBIDDEN The connection's current security level is lower than the one required by the write permissions of the CCCD associated with this characteristic.
 * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied.
 * @retval ::NRF_ERROR_BUSY For @ref BLE_GATT_HVX_INDICATION Procedure already in progress. Wait for a @ref BLE_GATTS_EVT_HVC event and retry.
 * @retval ::BLE_ERROR_GATTS_SYS_ATTR_MISSING System attributes missing, use @ref sd_ble_gatts_sys_attr_set to set them to a known value.
 * @retval ::NRF_ERROR_RESOURCES Too many notifications queued.
 *                               Wait for a @ref BLE_GATTS_EVT_HVN_TX_COMPLETE event and retry.
 * @retval ::NRF_ERROR_TIMEOUT There has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.
 */

before PR

///Notify or Indicate an attribute value.
///
///This function checks for the relevant Client Characteristic Configuration descriptor value to verify that the relevant operation
///(notification or indication) has been enabled by the client. It is also able to update the attribute value before issuing the PDU, so that
///the application can atomically perform a value update and a server initiated transaction with a single API call.
///The Attribute Table has been updated if one of the following error codes is returned: [`NRF_ERROR_INVALID_STATE`] [`NRF_ERROR_BUSY`]
///[`NRF_ERROR_FORBIDDEN`] [`BLE_ERROR_GATTS_SYS_ATTR_MISSING`] and [`NRF_ERROR_RESOURCES`]
///The caller can check whether the value has been updated by looking at the contents of [`ble_gatts_hvx_params_t::p_len)`]
///If the application tries to indicate an attribute value while another indication procedure is ongoing,
///the function call will return [`NRF_ERROR_BUSY`]
///A [`BLE_GATTS_EVT_HVC`] event will be issued as soon as the confirmation arrives from the peer.
///When the queue is full, the function call will return [`NRF_ERROR_RESOURCES`]
///A [`BLE_GATTS_EVT_HVN_TX_COMPLETE`] event will be issued as soon as the transmission of the notification is complete.
///- Store initial queue element count in a variable.
///- Decrement the variable, which stores the currently available queue element count, by one when a call to this function returns [`NRF_SUCCESS`]
///- Increment the variable, which stores the current available queue element count, by the count variable in [`BLE_GATTS_EVT_HVN_TX_COMPLETE`] event.
///[`BLE_GATTS_EVT_HVN_TX_COMPLETE`] Notification transmission complete.}
///[`BLE_GATTS_EVT_HVC`] Confirmation received from the peer.}
///[`BLE_GATTS_HVX_SYS_ATTRS_MISSING_MSC}`]
///[`BLE_GATTS_HVN_MSC}`]
///[`BLE_GATTS_HVI_MSC}`]
///[`BLE_GATTS_HVX_DISABLED_MSC}`]
///contains a non-NULL pointer the attribute value will be updated with the contents
///pointed by it before sending the notification or indication. If the attribute value
///is updated, [`ble_gatts_hvx_params_t::p_len`] is updated by the SoftDevice to
///contain the number of actual bytes written, else it will be set to 0.
///- Invalid Connection State
///- Notifications and/or indications not enabled in the CCCD
///- An ATT_MTU exchange is ongoing
///Wait for a [`BLE_GATTS_EVT_HVN_TX_COMPLETE`] event and retry.
///
///# Arguments
///
///* `conn_handle` - Connection handle. [Direction: In]
///* `p_hvx_params` - Pointer to an HVx parameters structure. If [`ble_gatts_hvx_params_t::p_data`] [Direction: Out]
///
///# Return values
///* ::NRF_SUCCESS Successfully queued a notification or indication for transmission, and optionally updated the attribute value.
///* ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
///* ::NRF_ERROR_INVALID_STATE One or more of the following is true:
///* ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
///* ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
///* ::BLE_ERROR_INVALID_ATTR_HANDLE Invalid attribute handle(s) supplied. Only attributes added directly by the application are available to notify and indicate.
///* ::BLE_ERROR_GATTS_INVALID_ATTR_TYPE Invalid attribute type(s) supplied, only characteristic values may be notified and indicated.
///* ::NRF_ERROR_NOT_FOUND Attribute not found.
///* ::NRF_ERROR_FORBIDDEN The connection's current security level is lower than the one required by the write permissions of the CCCD associated with this characteristic.
///* ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied.
///* ::NRF_ERROR_BUSY For [`BLE_GATT_HVX_INDICATION`] Procedure already in progress. Wait for a [`BLE_GATTS_EVT_HVC`] event and retry.
///* ::BLE_ERROR_GATTS_SYS_ATTR_MISSING System attributes missing, use [`sd_ble_gatts_sys_attr_set`] to set them to a known value.
///* ::NRF_ERROR_RESOURCES Too many notifications queued.
///* ::NRF_ERROR_TIMEOUT There has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.
///
///# Notes
///
///* The local attribute value may be updated even if an outgoing packet is not sent to the peer due to an error during execution.
///* Only one indication procedure can be ongoing per connection at a time.
///* The number of Handle Value Notifications that can be queued is configured by [`ble_gatts_conn_cfg_t::hvn_tx_queue_size`]
///* The application can keep track of the available queue element count for notifications by following the procedure below:
///

after PR

///Notify or Indicate an attribute value.
///
///This function checks for the relevant Client Characteristic Configuration descriptor value to verify that the relevant operation (notification or indication) has been enabled by the client. It is also able to update the attribute value before issuing the PDU, so that the application can atomically perform a value update and a server initiated transaction with a single API call.
///[`BLE_GATTS_EVT_HVN_TX_COMPLETE`] Notification transmission complete.} [`BLE_GATTS_EVT_HVC`] Confirmation received from the peer.}
///
///# Arguments
///
///* `conn_handle` - [Direction: In] Connection handle.
///* `p_hvx_params` - [Direction: Out] Pointer to an HVx parameters structure. If [`ble_gatts_hvx_params_t::p_data`] contains a non-NULL pointer the attribute value will be updated with the contents pointed by it before sending the notification or indication. If the attribute value is updated,  [`ble_gatts_hvx_params_t::p_len`] is updated by the SoftDevice to contain the number of actual bytes written, else it will be set to 0.
///
///# Return values
///* ::NRF_SUCCESS Successfully queued a notification or indication for transmission, and optionally updated the attribute value.
///* ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
///* ::NRF_ERROR_INVALID_STATE One or more of the following is true:
///  * Invalid Connection State
///  * Notifications and/or indications not enabled in the CCCD
///  * An ATT_MTU exchange is ongoing
///* ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
///* ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
///* ::BLE_ERROR_INVALID_ATTR_HANDLE Invalid attribute handle(s) supplied. Only attributes added directly by the application are available to notify and indicate.
///* ::BLE_ERROR_GATTS_INVALID_ATTR_TYPE Invalid attribute type(s) supplied, only characteristic values may be notified and indicated.
///* ::NRF_ERROR_NOT_FOUND Attribute not found.
///* ::NRF_ERROR_FORBIDDEN The connection's current security level is lower than the one required by the write permissions of the CCCD associated with this characteristic.
///* ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied.
///* ::NRF_ERROR_BUSY For [`BLE_GATT_HVX_INDICATION`] Procedure already in progress. Wait for a [`BLE_GATTS_EVT_HVC`] event and retry.
///* ::BLE_ERROR_GATTS_SYS_ATTR_MISSING System attributes missing, use [`sd_ble_gatts_sys_attr_set`] to set them to a known value.
///* ::NRF_ERROR_RESOURCES Too many notifications queued. Wait for a  [`BLE_GATTS_EVT_HVN_TX_COMPLETE`] event and retry.
///* ::NRF_ERROR_TIMEOUT There has been a GATT procedure timeout. No new GATT procedure can be performed without reestablishing the connection.
///
///# Notes
///
///* The local attribute value may be updated even if an outgoing packet is not sent to the peer due to an error during execution. The Attribute Table has been updated if one of the following error codes is returned:  [`NRF_ERROR_INVALID_STATE`]  [`NRF_ERROR_BUSY`] [`NRF_ERROR_FORBIDDEN`]  [`BLE_ERROR_GATTS_SYS_ATTR_MISSING`] and  [`NRF_ERROR_RESOURCES`] The caller can check whether the value has been updated by looking at the contents of  [`ble_gatts_hvx_params_t::p_len)`]
///* Only one indication procedure can be ongoing per connection at a time. If the application tries to indicate an attribute value while another indication procedure is ongoing, the function call will return  [`NRF_ERROR_BUSY`] A  [`BLE_GATTS_EVT_HVC`] event will be issued as soon as the confirmation arrives from the peer.
///* The number of Handle Value Notifications that can be queued is configured by [`ble_gatts_conn_cfg_t::hvn_tx_queue_size`] When the queue is full, the function call will return  [`NRF_ERROR_RESOURCES`] A  [`BLE_GATTS_EVT_HVN_TX_COMPLETE`] event will be issued as soon as the transmission of the notification is complete.
///* The application can keep track of the available queue element count for notifications by following the procedure below:
///  * Store initial queue element count in a variable.
///  * Decrement the variable, which stores the currently available queue element count, by one when a call to this function returns  [`NRF_SUCCESS`]
///  * Increment the variable, which stores the current available queue element count, by the count variable in  [`BLE_GATTS_EVT_HVN_TX_COMPLETE`] event.
///

generated docs before PR

generated docs after PR

[Techie-Pi]

This is great! :)
I've wanted to fix this for some time now, but I didn't have the time to do so.

I'll probably review this tomorrow in depth, for now I would like you to run rustfmt, because it looks like it could fix a few formatting issues.
Thanks for the PR! 😄

[PingPongun]

I ran rustfmt with default settings, but I'm not sure if it's what you expected, as formatting in places I haven't touched also changed.

[Techie-Pi]

Just a question, but this looks like a sensible approach :)
I would like to change a few things about documentation, but I'll change them myself once the PR is merged

[Techie-Pi]

Is this else if needed?

[PingPongun]

Yes it allows spaces between sublist mark('-', '*', '+') and sublist text to be skipped
eg. ( '_' is whitespace skipped by 'first if'; '.' is whitespace skipped by this else if):
_ _ _ _-....sublist text
but it can be done also in other ways (maybe simpler as I think about it now), eg.

    for ch in line.chars() {
        if ch.is_whitespace() {
            leading_whitespaces += 1;
        } else if ch == '-' || ch == '*' || ch == '+' {
            sublist = true;
            chars_to_skip = leading_whitespaces + 1;
            break;
        } else {
            chars_to_skip = leading_whitespaces;
            break;
        };
    }
    line.drain(..chars_to_skip); //remove whitespace and sublist mark
    line.trim_start();

[Techie-Pi]

Yeah, that looks simpler, maybe you could change it

[Techie-Pi]

Thank you for this :)
I'll improve the docs this weekend and publish a new version next week or so