Alternative modes for combining mapping data

[sciwhiz12]

Currently, Compass relies on the MappingUtil#apply method from Feather to apply the input data onto the production data to produce the staging data.

However, the design of the method leaves an undesirable design gotcha:

Let us imagine a case where a contributor wishes to map a parameter with a name. Using the simple input format (as described in the wiki), the input data would look like the following:

class com/example/SomeClass
    method someMethod (I)V
        param 1 pInputNum

However, this causes a problem is either the class or method contains a javadoc. MappingUtil#apply works by using the javadoc values from the input data if an entry is present, otherwise it uses the javadoc values from the base data. Because of this current implementation, the data given would overwrite any stored javadocs from the base data with the ones from the input, which is empty, so this effectively erases the javadocs.

This is undesirable because instead of just mapping a parameter as was the contributor's original intention, they have now potentially wiped out the javadocs of the enclosing class and method by accident.

To resolve this, there should be three operating modes for the input system, in increasing order of 'safety':

• FULL-OVERWRITE - maintains the current behavior, where if an entry is present in the input data, the javadocs (or parameter names) from the input data always overwrite over the javadocs or names from the base data (even if the javadocs is empty). This allows for 'erasing' data by adding entries with no data.
• OVERWRITE - the javadocs or param names from the base data is only overwritten if there is an entry present in the input data, and the javadocs is non-empty (or the param name is notyet set). This should be the default mode for the inputs system.
• ADDITIVE - the javadocs or param names from the base data is never overwritten. The javadocs from the input data are only added to the base data if there is no existing javadocs in the base data. This is useful for importing javadocs from other verisons, without overwriting already existing javadocs (which may be more up-to-date for that version).

The names of the first two modes needs reconsidering, to avoid a compound word for the first one.

[sciwhiz12]

The names of the three modes will be OVERWRITE, OVERRIDE, and ADDITIVE.
OVERWRITE means data is always overwritten with the one from the inputs (even if empty), OVERRIDE implies data is only overriden if there is non-empty data from the inputs, and ADDTIVIE implies data is only added to by the inputs, and never overriden or overwritten.

To implement this, the createStagingFromInputs task will be made into its own task class, with a property with an enum of the three modes, which can be set using a command line option.