From 286049fdb5780fdf0b151fdc76d9cf5eb95371f0 Mon Sep 17 00:00:00 2001 From: Pawel Piech Date: Thu, 24 Sep 2009 17:29:15 +0000 Subject: [PATCH] Added missing API comments. --- .../debug/ui/viewmodel/IDebugVMConstants.java | 45 ++++++++++++++++- .../numberformat/FormattedValueVMUtil.java | 50 +++++++++++++++++-- .../viewmodel/update/ICachingVMProvider.java | 15 ++++++ 3 files changed, 106 insertions(+), 4 deletions(-) diff --git a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/debug/ui/viewmodel/IDebugVMConstants.java b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/debug/ui/viewmodel/IDebugVMConstants.java index 751cc62f2ce..b8b6386454a 100644 --- a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/debug/ui/viewmodel/IDebugVMConstants.java +++ b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/debug/ui/viewmodel/IDebugVMConstants.java @@ -16,6 +16,7 @@ import org.eclipse.cdt.dsf.internal.ui.DsfUIPlugin; import org.eclipse.cdt.dsf.ui.viewmodel.update.ICachingVMProvider; /** + * Public constants used in the debug view model. * * @since 1.0 */ @@ -32,38 +33,80 @@ public interface IDebugVMConstants { public static final String COLUMN_ID__EXPRESSION = DsfUIPlugin.PLUGIN_ID + ".COLUMN_ID__EXPRESSION"; //$NON-NLS-1$ /** - * Location of the current format in the IPresentationContext data store. + * Property name used to store the selected number format in a + * presentation context. * + * @see org.eclipse.debug.internal.ui.viewers.model.provisional.IPresentationContext * @since 2.0 */ public final static String PROP_FORMATTED_VALUE_FORMAT_PREFERENCE = "CurrentNumericStyle" ; //$NON-NLS-1$ /** + * Property for an element's value represented in the active number format. + * + * @see org.eclipse.cdt.dsf.ui.viewmodel.properties.IElementPropertiesProvider + * @see org.eclipse.cdt.dsf.debug.ui.viewmodel.numberformat.FormattedValueVMUtil + * @see org.eclipse.cdt.dsf.debug.service.IFormattedValues + * * @since 2.0 */ public static final String PROP_FORMATTED_VALUE_ACTIVE_FORMAT_VALUE = "formatted_value_active_format_value"; //$NON-NLS-1$ /** + * Property for the available number formats for a given element. + * + * @see org.eclipse.cdt.dsf.ui.viewmodel.properties.IElementPropertiesProvider + * @see org.eclipse.cdt.dsf.debug.ui.viewmodel.numberformat.FormattedValueVMUtil + * @see org.eclipse.cdt.dsf.debug.service.IFormattedValues + * * @since 2.0 */ public static final String PROP_FORMATTED_VALUE_AVAILABLE_FORMATS = "formatted_value_available_formats"; //$NON-NLS-1$ /** + * Property for the active number format for a given element. + * + * @see org.eclipse.cdt.dsf.ui.viewmodel.properties.IElementPropertiesProvider + * @see org.eclipse.cdt.dsf.debug.ui.viewmodel.numberformat.FormattedValueVMUtil + * @see org.eclipse.cdt.dsf.debug.service.IFormattedValues + * * @since 2.0 */ public static final String PROP_FORMATTED_VALUE_ACTIVE_FORMAT = "formatted_value_active_format"; //$NON-NLS-1$ /** + * Prefix for properties representing a value of an element represented in + * a given number format. + * + * @see org.eclipse.cdt.dsf.debug.ui.viewmodel.numberformat.FormattedValueVMUtil#getPropertyForFormatId(String) + * @see org.eclipse.cdt.dsf.ui.viewmodel.properties.IElementPropertiesProvider + * @see org.eclipse.cdt.dsf.debug.service.IFormattedValues + * * @since 2.0 */ public static final String PROP_FORMATTED_VALUE_BASE = "formatted_value_base"; //$NON-NLS-1$ /** + * Property which indicates that the element's value formatted in a string + * format has changed value since the last time a cache has been flushed. + * + * @see org.eclipse.cdt.dsf.ui.viewmodel.properties.IElementPropertiesProvider + * @see org.eclipse.cdt.dsf.debug.ui.viewmodel.numberformat.FormattedValueVMUtil + * @see org.eclipse.cdt.dsf.debug.service.IFormattedValues + * * @since 2.0 */ public static final String PROP_IS_STRING_FORMAT_VALUE_CHANGED = ICachingVMProvider.PROP_IS_CHANGED_PREFIX + FormattedValueVMUtil.getPropertyForFormatId(IFormattedValues.STRING_FORMAT); /** + * Property which indicates that the element's value formatted using the + * element's active number format has changed value since the last time a + * cache has been flushed. + * + * @see org.eclipse.cdt.dsf.ui.viewmodel.properties.IElementPropertiesProvider + * @see org.eclipse.cdt.dsf.debug.ui.viewmodel.numberformat.FormattedValueVMUtil + * @see org.eclipse.cdt.dsf.debug.service.IFormattedValues + * * @since 2.0 */ public static final String PROP_IS_ACTIVE_FORMATTED_VALUE_CHANGED = ICachingVMProvider.PROP_IS_CHANGED_PREFIX + FormattedValueVMUtil.getPropertyForFormatId(IFormattedValues.NATURAL_FORMAT); diff --git a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/debug/ui/viewmodel/numberformat/FormattedValueVMUtil.java b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/debug/ui/viewmodel/numberformat/FormattedValueVMUtil.java index 66a7f887e6b..718f83900b6 100644 --- a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/debug/ui/viewmodel/numberformat/FormattedValueVMUtil.java +++ b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/debug/ui/viewmodel/numberformat/FormattedValueVMUtil.java @@ -33,13 +33,20 @@ import org.eclipse.cdt.dsf.ui.viewmodel.properties.IPropertiesUpdate; import org.eclipse.debug.internal.ui.viewers.model.provisional.IPresentationContext; /** + * A helper class for View Model Node implementations that support elements + * to be formatted using different number formats. The various static methods in + * this class handle populating the properties of an IPropertiesUpdate using data + * retrieved from a DSF service implementing {@link IFormattedValues} interface. + * + * @see org.eclipse.cdt.dsf.ui.viewmodel.properties.IElementPropertiesProvider + * @see org.eclipse.cdt.dsf.debug.service.IFormattedValues * * @since 2.0 */ public class FormattedValueVMUtil { /** - * Common map of user-readable labels for format IDs. UI components for + * Common map of user-readable labels for format IDs. */ private static Map fFormatLabels = new HashMap(8); @@ -52,10 +59,20 @@ public class FormattedValueVMUtil { setFormatLabel(IFormattedValues.STRING_FORMAT, MessagesForNumberFormat.FormattedValueVMUtil_String_format__label); } + /** + * Adds a user-readable label for a given format ID. If a given view model has a custom format ID, it can + * add its label to the map of format IDs using this method. + * + * @param formatId Format ID to set the label for. + * @param label User-readable lable for a format. + */ public static void setFormatLabel(String formatId, String label) { fFormatLabels.put(formatId, label); } + /** + * Returns a user readable label for a given format ID. + */ public static String getFormatLabel(String formatId) { String label = fFormatLabels.get(formatId); if (label != null) { @@ -66,6 +83,9 @@ public class FormattedValueVMUtil { } } + /** + * Returns an element property representing an element value in a given format. + */ public static String getPropertyForFormatId(String formatId) { if (formatId == null) { return null; @@ -73,11 +93,19 @@ public class FormattedValueVMUtil { return IDebugVMConstants.PROP_FORMATTED_VALUE_BASE + "." + formatId; //$NON-NLS-1$ } + /** + * Returns a format ID based on the element property representing a + * formatted element value. + */ public static String getFormatFromProperty(String property) { return property.substring(IDebugVMConstants.PROP_FORMATTED_VALUE_BASE.length() + 1); } - + + /** + * Returns the user-selected number format that is saved in the given + * presentation context. + */ public static String getPreferredFormat(IPresentationContext context) { Object prop = context.getProperty( IDebugVMConstants.PROP_FORMATTED_VALUE_FORMAT_PREFERENCE ); if ( prop != null ) { @@ -85,7 +113,23 @@ public class FormattedValueVMUtil { } return IFormattedValues.NATURAL_FORMAT; } - + + /** + * This method fills in the formatted value properties in the given array + * of property update objects using data retrieved from the given + * formatted values service. + * + * @param updates The array of updates to fill in information to. This + * update is used to retrieve the data model context and to write the + * properties into. + * @param service The service to be used to retrieve the values from. + * @param dmcType The class type of the data model context. Some updates + * can contain multiple formatted data data model contexts, and this + * method assures that there is no ambiguity in which context should be + * used. + * @param monitor Request monitor that will be called when all the + * updates are completed. + */ @ConfinedToDsfExecutor("service.getExecutor()") public static void updateFormattedValues( final IPropertiesUpdate updates[], diff --git a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/update/ICachingVMProvider.java b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/update/ICachingVMProvider.java index 4e31076f1df..3640815aef8 100644 --- a/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/update/ICachingVMProvider.java +++ b/dsf/org.eclipse.cdt.dsf.ui/src/org/eclipse/cdt/dsf/ui/viewmodel/update/ICachingVMProvider.java @@ -23,11 +23,26 @@ import org.eclipse.cdt.dsf.ui.viewmodel.properties.IElementPropertiesProvider; public interface ICachingVMProvider extends IVMProvider, IElementPropertiesProvider { /** + * A prefix used to create a property to indicate whether a given property + * has changed since the last cache update with the {@link IVMUpdatePolicy#ARCHIVE} + * flag. The caching VM provider appends these properties to an element's set of + * properties as they are retrieved through the cache. + * + * @see org.eclipse.cdt.dsf.ui.viewmodel.properties.IElementPropertiesProvider + * @see IVMUpdatePolicy#ARCHIVE + * * @since 2.0 */ public static final String PROP_IS_CHANGED_PREFIX = "is_changed."; //$NON-NLS-1$ /** + * A prefix used to create a property to indicate whether a given property + * is currently dirty. The caching VM provider appends these properties to an + * element's set of properties as they are retrieved through the cache. + * + * @see org.eclipse.cdt.dsf.ui.viewmodel.properties.IElementPropertiesProvider + * @see IVMUpdatePolicy#DIRTY + * * @since 2.0 */ public static final String PROP_CACHE_ENTRY_DIRTY = "cache_entry_dirty"; //$NON-NLS-1$