/*!
 *  ======== Warnings ========
 *  Conditional warnings manager
 *  @nodoc
 *  This module declares all warnings generated by the packages in the xdc.*
 *  name space. Each warning is identified with an ID, a positive integer
 *  number. A warning message allows conversion specifiers that can be replaced 
 *  with actual strings at the time a warning message is generated.
 *  The purpose of IDs is to let users find warning documentation in this module
 *  and also to allow warnings to be disabled based on their IDs.
 */
metaonly module Warnings {
    typedef String StringArray[];

    /*!
     *  ======== Warning ========
     *  Warning descriptor
     *
     *  Warnings are defined as instances of this structure, and also that's
     *  how the warnings are kept internally.
     */
    struct Warning {
        Int id;
        String msg;
    }

    /*!
     *  ======== WarningParams ========
     *  Structure passed to $logWarning
     *
     *  Currently, the only parameter assigned to a warning is an array of
     *  strings to replace conversion specifiers in `Warning`s. In the future,
     *  a caller can identify a module where the warning is defined, which will
     *  allow any package to introduce new warnings.
     */
    struct WarningParams {
        Warning warning;
        StringArray args;
    }

    /*!
     *  ======== LOGID ========
     *  Multiple Log events with the same ID
     *
     *  If two Log events share a message, they are automatically assigned
     *  the same ID because IDs also serve as pointers to an array that holds
     *  a compact representation of message strings. To avoid duplication of
     *  strings, if a string already exists in the array, the ID of the 
     *  existing copy is used.
     *
     *  This warning can be useful for package producers who unintentionally
     *  declare two events with the same message, which could be combined
     *  into one common Log event.
     */
    const Warning LOGID = {
        id: 4,
        msg: "Two events with the same id: %s and %s share the msg: '%s'. You must reconfigure the message of one of these events to ensure its id will be unique."
    };

    /*!
     *  ======== disable ========
     *  Internal function that disables warnings
     *
     *  @param(ids)    array of IDs
     */
    Void disable(StringArray ids);

    /*!
     *  ======== getMessage ========
     *  Internal function that creates an actual output message
     *
     *  @param(prms)    WarningParams structure passed by the warning
     *                  generation code
     */
    String getMessage(WarningParams prms);
}