1    /*!
     2     *  ======== Warnings ========
     3     *  Conditional warnings manager
     4     *  @nodoc
     5     *  This module declares all warnings generated by the packages in the xdc.*
     6     *  name space. Each warning is identified with an ID, a positive integer
     7     *  number. A warning message allows conversion specifiers that can be replaced 
     8     *  with actual strings at the time a warning message is generated.
     9     *  The purpose of IDs is to let users find warning documentation in this module
    10     *  and also to allow warnings to be disabled based on their IDs.
    11     */
    12    metaonly module Warnings {
    13        typedef String StringArray[];
    14    
    15        /*!
    16         *  ======== Warning ========
    17         *  Warning descriptor
    18         *
    19         *  Warnings are defined as instances of this structure, and also that's
    20         *  how the warnings are kept internally.
    21         */
    22        struct Warning {
    23            Int id;
    24            String msg;
    25        }
    26    
    27        /*!
    28         *  ======== WarningParams ========
    29         *  Structure passed to $logWarning
    30         *
    31         *  Currently, the only parameter assigned to a warning is an array of
    32         *  strings to replace conversion specifiers in `Warning`s. In the future,
    33         *  a caller can identify a module where the warning is defined, which will
    34         *  allow any package to introduce new warnings.
    35         */
    36        struct WarningParams {
    37            Warning warning;
    38            StringArray args;
    39        }
    40    
    41        /*!
    42         *  ======== LOGID ========
    43         *  Multiple Log events with the same ID
    44         *
    45         *  If two Log events share a message, they are automatically assigned
    46         *  the same ID because IDs also serve as pointers to an array that holds
    47         *  a compact representation of message strings. To avoid duplication of
    48         *  strings, if a string already exists in the array, the ID of the 
    49         *  existing copy is used.
    50         *
    51         *  This warning can be useful for package producers who unintentionally
    52         *  declare two events with the same message, which could be combined
    53         *  into one common Log event.
    54         */
    55        const Warning LOGID = {
    56            id: 4,
    57            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."
    58        };
    59    
    60        /*!
    61         *  ======== disable ========
    62         *  Internal function that disables warnings
    63         *
    64         *  @param(ids)    array of IDs
    65         */
    66        Void disable(StringArray ids);
    67    
    68        /*!
    69         *  ======== getMessage ========
    70         *  Internal function that creates an actual output message
    71         *
    72         *  @param(prms)    WarningParams structure passed by the warning
    73         *                  generation code
    74         */
    75        String getMessage(WarningParams prms);
    76    }
    77    /*
    78     *  @(#) xdc; 1, 1, 1,0; 2-20-2019 10:21:34; /db/ztree/library/trees/xdc/xdc-F09/src/packages/
    79     */
    80