mirror of
https://github.com/NationalSecurityAgency/ghidra.git
synced 2025-10-06 03:50:02 +02:00
GP-1361 - Updated auto comments to show user-defined repeatable comments
from the reference destination Closes #2475
This commit is contained in:
dragonmacher
parent
f9463e600d
commit
a54d0e28d6
5 changed files with 170 additions and 90 deletions
|
|
@ -38,11 +38,11 @@ public interface Composite extends DataType {
|
|||
public abstract int getNumComponents();
|
||||
|
||||
/**
|
||||
* Returns the number of explicitly defined components in this composite.
|
||||
* For Unions and packed Structures this is equivalent to {@link #getNumComponents()}
|
||||
* since they do not contain undefined components.
|
||||
* This count will always exclude all undefined filler components which may be present
|
||||
* within a Structure whoose packing is disabled (see {@link #isPackingEnabled()}).
|
||||
* Returns the number of explicitly defined components in this composite.
|
||||
* For Unions and packed Structures this is equivalent to {@link #getNumComponents()}
|
||||
* since they do not contain undefined components.
|
||||
* This count will always exclude all undefined filler components which may be present
|
||||
* within a Structure whose packing is disabled (see {@link #isPackingEnabled()}).
|
||||
* @return the number of explicitly defined components in this composite
|
||||
*/
|
||||
public abstract int getNumDefinedComponents();
|
||||
|
|
@ -66,8 +66,8 @@ public interface Composite extends DataType {
|
|||
/**
|
||||
* Returns an array of Data Type Components that make up this composite excluding
|
||||
* undefined filler components which may be present within Structures where packing is disabled.
|
||||
* The number of components corresponds to {@link #getNumDefinedComponents()}. For Unions and
|
||||
* packed Structures this is equivalent to {@link #getComponents()}
|
||||
* The number of components corresponds to {@link #getNumDefinedComponents()}. For Unions and
|
||||
* packed Structures this is equivalent to {@link #getComponents()}
|
||||
* since they do not contain undefined filler components.
|
||||
* @return array all explicitly defined components
|
||||
*/
|
||||
|
|
@ -78,7 +78,7 @@ public interface Composite extends DataType {
|
|||
* to use for adding components to an aligned structure for fixed-length dataTypes.
|
||||
* @param dataType the datatype to add.
|
||||
* @return the DataTypeComponent created.
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* allowed to be added to this composite data type.
|
||||
* For example, suppose dt1 contains dt2. Therefore it is not valid
|
||||
* to add dt1 to dt2 since this would cause a cyclic dependency.
|
||||
|
|
@ -87,13 +87,13 @@ public interface Composite extends DataType {
|
|||
|
||||
/**
|
||||
* Adds a new datatype to the end of this composite. This is the preferred method
|
||||
* to use for adding components to an aligned structure for dynamic dataTypes such as
|
||||
* to use for adding components to an aligned structure for dynamic dataTypes such as
|
||||
* strings whose length must be specified.
|
||||
* @param dataType the datatype to add.
|
||||
* @param length the length to associate with the datatype.
|
||||
* For fixed length types a length <= 0 will use the length of the resolved dataType.
|
||||
* @return the componentDataType created.
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* allowed to be added to this composite data type or an invalid length
|
||||
* is specified.
|
||||
* For example, suppose dt1 contains dt2. Therefore it is not valid
|
||||
|
|
@ -108,7 +108,7 @@ public interface Composite extends DataType {
|
|||
* @param name the field name to associate with this component.
|
||||
* @param comment the comment to associate with this component.
|
||||
* @return the componentDataType created.
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* allowed to be added to this composite data type.
|
||||
* For example, suppose dt1 contains dt2. Therefore it is not valid
|
||||
* to add dt1 to dt2 since this would cause a cyclic dependency.
|
||||
|
|
@ -117,8 +117,8 @@ public interface Composite extends DataType {
|
|||
throws IllegalArgumentException;
|
||||
|
||||
/**
|
||||
* Adds a new bitfield to the end of this composite. This method is intended
|
||||
* to be used with packed structures/unions only where the bitfield will be
|
||||
* Adds a new bitfield to the end of this composite. This method is intended
|
||||
* to be used with packed structures/unions only where the bitfield will be
|
||||
* appropriately packed. The minimum storage storage byte size will be applied.
|
||||
* It will not provide useful results for composites with packing disabled.
|
||||
* @param baseDataType the bitfield base datatype (certain restrictions apply).
|
||||
|
|
@ -135,7 +135,7 @@ public interface Composite extends DataType {
|
|||
|
||||
/**
|
||||
* Adds a new datatype to the end of this composite. This is the preferred method
|
||||
* to use for adding components to an aligned structure for dynamic dataTypes such as
|
||||
* to use for adding components to an aligned structure for dynamic dataTypes such as
|
||||
* strings whose length must be specified.
|
||||
* @param dataType the datatype to add.
|
||||
* @param length the length to associate with the datatype.
|
||||
|
|
@ -143,7 +143,7 @@ public interface Composite extends DataType {
|
|||
* @param name the field name to associate with this component.
|
||||
* @param comment the comment to associate with this component.
|
||||
* @return the componentDataType created.
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* allowed to be added to this composite data type or an invalid length is specified.
|
||||
* For example, suppose dt1 contains dt2. Therefore it is not valid
|
||||
* to add dt1 to dt2 since this would cause a cyclic dependency.
|
||||
|
|
@ -155,10 +155,10 @@ public interface Composite extends DataType {
|
|||
* Inserts a new datatype at the specified ordinal position in this composite.
|
||||
* <BR>Note: For an aligned structure the ordinal position will get adjusted
|
||||
* automatically to provide the proper alignment.
|
||||
* @param ordinal the ordinal where the new datatype is to be inserted.
|
||||
* @param ordinal the ordinal where the new datatype is to be inserted.
|
||||
* @param dataType the datatype to insert.
|
||||
* @return the componentDataType created.
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* allowed to be inserted into this composite data type.
|
||||
* For example, suppose dt1 contains dt2. Therefore it is not valid
|
||||
* to insert dt1 to dt2 since this would cause a cyclic dependency.
|
||||
|
|
@ -171,13 +171,13 @@ public interface Composite extends DataType {
|
|||
* Inserts a new datatype at the specified ordinal position in this composite.
|
||||
* <BR>Note: For an aligned structure the ordinal position will get adjusted
|
||||
* automatically to provide the proper alignment.
|
||||
* @param ordinal the ordinal where the new datatype is to be inserted.
|
||||
* @param ordinal the ordinal where the new datatype is to be inserted.
|
||||
* @param dataType the datatype to insert.
|
||||
* @param length the length to associate with the datatype.
|
||||
* For fixed length types a length <= 0 will use the length of the resolved dataType.
|
||||
* @return the componentDataType created.
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* allowed to be inserted into this composite data type or an invalid
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* allowed to be inserted into this composite data type or an invalid
|
||||
* length is specified.
|
||||
* For example, suppose dt1 contains dt2. Therefore it is not valid
|
||||
* to insert dt1 to dt2 since this would cause a cyclic dependency.
|
||||
|
|
@ -190,14 +190,14 @@ public interface Composite extends DataType {
|
|||
* Inserts a new datatype at the specified ordinal position in this composite.
|
||||
* <BR>Note: For an aligned structure the ordinal position will get adjusted
|
||||
* automatically to provide the proper alignment.
|
||||
* @param ordinal the ordinal where the new datatype is to be inserted.
|
||||
* @param ordinal the ordinal where the new datatype is to be inserted.
|
||||
* @param dataType the datatype to insert.
|
||||
* @param length the length to associate with the datatype.
|
||||
* For fixed length types a length <= 0 will use the length of the resolved dataType.
|
||||
* @param name the field name to associate with this component.
|
||||
* @param comment the comment to associate with this component.
|
||||
* @return the componentDataType created.
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* @throws IllegalArgumentException if the specified data type is not
|
||||
* allowed to be inserted into this composite data type or an invalid length
|
||||
* is specified.
|
||||
* For example, suppose dt1 contains dt2. Therefore it is not valid
|
||||
|
|
@ -209,7 +209,7 @@ public interface Composite extends DataType {
|
|||
|
||||
/**
|
||||
* Deletes the component at the given ordinal position.
|
||||
* <BR>Note: Removal of bitfields from a structure with packing disabled will
|
||||
* <BR>Note: Removal of bitfields from a structure with packing disabled will
|
||||
* not shift other components causing vacated bytes to revert to undefined filler.
|
||||
* @param ordinal the ordinal of the component to be deleted.
|
||||
* @throws IndexOutOfBoundsException if component ordinal is out of bounds
|
||||
|
|
@ -218,7 +218,7 @@ public interface Composite extends DataType {
|
|||
|
||||
/**
|
||||
* Deletes the specified set of components at the given ordinal positions.
|
||||
* <BR>Note: Removal of bitfields from a structure with packing disabled will
|
||||
* <BR>Note: Removal of bitfields from a structure with packing disabled will
|
||||
* not shift other components causing vacated bytes to revert to undefined filler.
|
||||
* @param ordinals the ordinals of the component to be deleted.
|
||||
* @throws IndexOutOfBoundsException if any specified component ordinal is out of bounds
|
||||
|
|
@ -232,7 +232,7 @@ public interface Composite extends DataType {
|
|||
* <br>containing the data type directly
|
||||
* <br>containing another data type that has the data type as a part of it.
|
||||
* @param dataType the data type to look for.
|
||||
* @return true if the indicated data type is part of a sub-component of
|
||||
* @return true if the indicated data type is part of a sub-component of
|
||||
* this data type.
|
||||
*/
|
||||
public abstract boolean isPartOf(DataType dataType);
|
||||
|
|
@ -271,7 +271,7 @@ public interface Composite extends DataType {
|
|||
}
|
||||
|
||||
/**
|
||||
* Sets whether this data type's internal components are currently packed. The
|
||||
* Sets whether this data type's internal components are currently packed. The
|
||||
* affect of disabled packing differs between {@link Structure} and {@link Union}. When
|
||||
* packing disabled:
|
||||
* <ul>
|
||||
|
|
@ -280,11 +280,11 @@ public interface Composite extends DataType {
|
|||
* <li>Unions always place components at offset 0 and do not pad for alignment.
|
||||
* </ul>
|
||||
* In addition, when packing is disabled the default alignment is always 1 unless a
|
||||
* different minimum alignment has been set. When packing is enabled the overall
|
||||
* composite length infleunced by the composite's minimum alignment setting.
|
||||
* If a change in enablement occurs, the default alignment and packing behavior
|
||||
* different minimum alignment has been set. When packing is enabled the overall
|
||||
* composite length influenced by the composite's minimum alignment setting.
|
||||
* If a change in enablement occurs, the default alignment and packing behavior
|
||||
* will be used.
|
||||
* @param enabled true enables packing of components respecting component
|
||||
* @param enabled true enables packing of components respecting component
|
||||
* alignment and pack setting, whereas false disables packing.
|
||||
*/
|
||||
public void setPackingEnabled(boolean enabled);
|
||||
|
|
@ -306,19 +306,19 @@ public interface Composite extends DataType {
|
|||
}
|
||||
|
||||
/**
|
||||
* Gets the current packing value (typically a power of 2).
|
||||
* If this isn't a packed composite with an explicit packing value (see {@link #hasExplicitPackingValue()})
|
||||
* then the return value is undefined.
|
||||
* Gets the current packing value (typically a power of 2).
|
||||
* If this isn't a packed composite with an explicit packing value (see {@link #hasExplicitPackingValue()})
|
||||
* then the return value is undefined.
|
||||
* @return the current packing value or an undefined non-positive value
|
||||
*/
|
||||
public int getExplicitPackingValue();
|
||||
|
||||
/**
|
||||
* Sets the pack value for this composite (positive value, usually a power of 2).
|
||||
* If packing was previously disabled, packing will be enabled. This value will
|
||||
* establish the maximum effective alignment for this composite and each of the
|
||||
* components during the alignment computation (e.g., a value of 1 will eliminate
|
||||
* any padding). The overall composite length may be infleunced by the composite's
|
||||
* Sets the pack value for this composite (positive value, usually a power of 2).
|
||||
* If packing was previously disabled, packing will be enabled. This value will
|
||||
* establish the maximum effective alignment for this composite and each of the
|
||||
* components during the alignment computation (e.g., a value of 1 will eliminate
|
||||
* any padding). The overall composite length may be influenced by the composite's
|
||||
* minimum alignment setting.
|
||||
* @param packingValue the new positive packing value.
|
||||
* @throws IllegalArgumentException if a non-positive value is specified.
|
||||
|
|
@ -335,10 +335,10 @@ public interface Composite extends DataType {
|
|||
}
|
||||
|
||||
/**
|
||||
* Enables default packing behavior.
|
||||
* If packing was previously disabled, packing will be enabled.
|
||||
* Enables default packing behavior.
|
||||
* If packing was previously disabled, packing will be enabled.
|
||||
* Composite will automatically pack based upon the alignment requirements
|
||||
* of its components with overall composite length possibly infleunced by the composite's
|
||||
* of its components with overall composite length possibly influenced by the composite's
|
||||
* minimum alignment setting.
|
||||
*/
|
||||
public void setToDefaultPacking();
|
||||
|
|
@ -358,16 +358,16 @@ public interface Composite extends DataType {
|
|||
abstract AlignmentType getAlignmentType();
|
||||
|
||||
/**
|
||||
* Whether or not this data type is using the default alignment. When Structure packing
|
||||
* Whether or not this data type is using the default alignment. When Structure packing
|
||||
* is disabled the default alignment is always 1 (see {@link Structure#setPackingEnabled(boolean)}.
|
||||
* @return true if this data type is using its default alignment.
|
||||
* @return true if this data type is using its default alignment.
|
||||
*/
|
||||
public default boolean isDefaultAligned() {
|
||||
return getAlignmentType() == AlignmentType.DEFAULT;
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether or not this data type is using the machine alignment value, specified by
|
||||
* Whether or not this data type is using the machine alignment value, specified by
|
||||
* {@link DataOrganization#getMachineAlignment()}, for its alignment.
|
||||
* @return true if this data type is using the machine alignment as its alignment.
|
||||
*/
|
||||
|
|
@ -376,8 +376,9 @@ public interface Composite extends DataType {
|
|||
}
|
||||
|
||||
/**
|
||||
* Determine if an explicit minimum alignment has been set (see {@link #getExplicitMinimumAlignment()}).
|
||||
* An undefined value is returned if default alignment or machine alignment is enabled.
|
||||
* Determine if an explicit minimum alignment has been set (see
|
||||
* {@link #getExplicitMinimumAlignment()}). An undefined value is returned if default alignment
|
||||
* or machine alignment is enabled.
|
||||
* @return true if an explicit minimum alignment has been set, else false
|
||||
*/
|
||||
public default boolean hasExplicitMinimumAlignment() {
|
||||
|
|
@ -385,20 +386,20 @@ public interface Composite extends DataType {
|
|||
}
|
||||
|
||||
/**
|
||||
* Get the explicitminimum alignment setting for this Composite which contributes
|
||||
* Get the explicit minimum alignment setting for this Composite which contributes
|
||||
* to the actual computed alignment value (see {@link #getAlignment()}.
|
||||
* @return the minimum alignment setting for this Composite or an undefined
|
||||
* @return the minimum alignment setting for this Composite or an undefined
|
||||
* non-positive value if an explicit minimum alignment has not been set.
|
||||
*/
|
||||
public int getExplicitMinimumAlignment();
|
||||
|
||||
/**
|
||||
* Sets this data type's explicit minimum alignment (positive value).
|
||||
* Sets this data type's explicit minimum alignment (positive value).
|
||||
* Together with the pack setting and component alignments will
|
||||
* affect the actual computed alignment of this composite.
|
||||
* When packing is enabled, the alignment setting may also affect padding
|
||||
* When packing is enabled, the alignment setting may also affect padding
|
||||
* at the end of the composite and its length. When packing is disabled,
|
||||
* this setting will not affect the length of thhis composite.
|
||||
* this setting will not affect the length of this composite.
|
||||
* @param minAlignment the minimum alignment for this Composite.
|
||||
* @throws IllegalArgumentException if a non-positive value is specified
|
||||
*/
|
||||
|
|
@ -416,14 +417,14 @@ public interface Composite extends DataType {
|
|||
/**
|
||||
* Sets this data type's alignment to its default alignment. For packed
|
||||
* composites, this data type's alignment will be based upon the components it contains and
|
||||
* its current pack settings. This is the default state and only needs to be used
|
||||
* when changing from a non-default alignment type.
|
||||
* its current pack settings. This is the default state and only needs to be used
|
||||
* when changing from a non-default alignment type.
|
||||
*/
|
||||
public void setToDefaultAligned();
|
||||
|
||||
/**
|
||||
* Sets this data type's minimum alignment to the machine alignment which is
|
||||
* specified by {@link DataOrganization#getMachineAlignment()}. The machine alignment is
|
||||
* Sets this data type's minimum alignment to the machine alignment which is
|
||||
* specified by {@link DataOrganization#getMachineAlignment()}. The machine alignment is
|
||||
* defined as the maximum useful alignment for the target machine.
|
||||
*/
|
||||
public void setToMachineAligned();
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue