`@Html.DisplayName()`, `.DisplayText()`, `.Id()`, `.Name()`, `.Value()` return `string`

- fixes #566 and part of #847
- allows compositions such as `@Html.Label("property", Html.Id("property"))`
  and `@Html.Raw(Html.DisplayText("property"))` (this one is not recommended)
- adjust XML comments to match
- add missing XML comments to `HtmlHelperValueExtensions`
- nit: `TInnerModel` -> `TModelItem`

- increase XML comment consistency for changed methods
 - generally make wording more consistent e.g. how we use words such as
   "returns"
 - use `<see langref="string|true|false|null"/>` more

src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelper.cs

@@ -248,17 +248,16 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <inheritdoc />
-        public HtmlString DisplayName(string expression)
+        public string DisplayName(string expression)
         {
             var metadata = ExpressionMetadataProvider.FromStringExpression(expression, ViewData, MetadataProvider);
             return GenerateDisplayName(metadata, expression);
         }
 
         /// <inheritdoc />
-        public HtmlString DisplayText(string name)
+        public string DisplayText(string name)
         {
             var metadata = ExpressionMetadataProvider.FromStringExpression(name, ViewData, MetadataProvider);
-
             return GenerateDisplayText(metadata);
         }
 
@@ -295,7 +294,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <inheritdoc />
-        public HtmlString Id(string name)
+        public string Id(string name)
         {
             return GenerateId(name);
         }
@@ -318,7 +317,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <inheritdoc />
-        public HtmlString Name(string name)
+        public string Name(string name)
         {
             return GenerateName(name);
         }
@@ -484,7 +483,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <inheritdoc />
-        public HtmlString Value([NotNull] string name, string format)
+        public string Value([NotNull] string name, string format)
         {
             return GenerateValue(name, value: null, format: format, useViewData: true);
         }
@@ -594,7 +593,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 htmlAttributes: htmlAttributeDictionary);
         }
 
-        protected virtual HtmlString GenerateDisplayName([NotNull] ModelMetadata metadata, string htmlFieldName)
+        protected virtual string GenerateDisplayName([NotNull] ModelMetadata metadata, string htmlFieldName)
         {
             // We don't call ModelMetadata.GetDisplayName here because
             // we want to fall back to the field name rather than the ModelType.
@@ -606,12 +605,12 @@ namespace Microsoft.AspNet.Mvc.Rendering
                     string.IsNullOrEmpty(htmlFieldName) ? string.Empty : htmlFieldName.Split('.').Last();
             }
 
-            return new HtmlString(Encode(resolvedDisplayName));
+            return resolvedDisplayName;
         }
 
-        protected virtual HtmlString GenerateDisplayText(ModelMetadata metadata)
+        protected virtual string GenerateDisplayText(ModelMetadata metadata)
         {
-            return new HtmlString(metadata.SimpleDisplayText);
+            return metadata.SimpleDisplayText ?? string.Empty;
         }
 
         protected HtmlString GenerateDropDown(ModelMetadata metadata, string expression,
@@ -722,9 +721,9 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 htmlAttributes: htmlAttributeDictionary);
         }
 
-        protected virtual HtmlString GenerateId(string expression)
+        protected virtual string GenerateId(string expression)
         {
-            return new HtmlString(Encode(ViewData.TemplateInfo.GetFullHtmlFieldName(expression)));
+            return ViewData.TemplateInfo.GetFullHtmlFieldName(expression);
         }
 
         protected virtual HtmlString GenerateLabel([NotNull] ModelMetadata metadata,
@@ -786,10 +785,10 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 htmlAttributes: htmlAttributes);
         }
 
-        protected virtual HtmlString GenerateName(string name)
+        protected virtual string GenerateName(string name)
         {
             var fullName = ViewData.TemplateInfo.GetFullHtmlFieldName(name);
-            return new HtmlString(Encode(fullName));
+            return fullName;
         }
 
         protected virtual HtmlString GeneratePassword(ModelMetadata metadata, string name, object value,
@@ -1301,7 +1300,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
             return divBuilder.ToHtmlString(TagRenderMode.Normal);
         }
 
-        protected virtual HtmlString GenerateValue(string name, object value, string format, bool useViewData)
+        protected virtual string GenerateValue(string name, object value, string format, bool useViewData)
         {
             var fullName = ViewData.TemplateInfo.GetFullHtmlFieldName(name);
             var attemptedValue = (string)GetModelStateValue(fullName, typeof(string));
@@ -1332,7 +1331,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
                 resolvedValue = FormatValue(value, format);
             }
 
-            return new HtmlString(Encode(resolvedValue));
+            return resolvedValue;
         }
 
         /// <inheritdoc />

src/Microsoft.AspNet.Mvc.Core/Rendering/Html/HtmlHelperOfT.cs

@@ -88,19 +88,19 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <inheritdoc />
-        public HtmlString DisplayNameFor<TValue>([NotNull] Expression<Func<TModel, TValue>> expression)
+        public string DisplayNameFor<TValue>([NotNull] Expression<Func<TModel, TValue>> expression)
         {
             var metadata = GetModelMetadata(expression);
             return GenerateDisplayName(metadata, ExpressionHelper.GetExpressionText(expression));
         }
 
         /// <inheritdoc />
-        public HtmlString DisplayNameForInnerType<TInnerModel, TValue>(
+        public string DisplayNameForInnerType<TModelItem, TValue>(
-            [NotNull] Expression<Func<TInnerModel, TValue>> expression)
+            [NotNull] Expression<Func<TModelItem, TValue>> expression)
         {
-            var metadata = ExpressionMetadataProvider.FromLambdaExpression<TInnerModel, TValue>(
+            var metadata = ExpressionMetadataProvider.FromLambdaExpression<TModelItem, TValue>(
                 expression,
-                new ViewDataDictionary<TInnerModel>(MetadataProvider),
+                new ViewDataDictionary<TModelItem>(MetadataProvider),
                 MetadataProvider);
 
             var expressionText = ExpressionHelper.GetExpressionText(expression);
@@ -113,7 +113,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <inheritdoc />
-        public HtmlString DisplayTextFor<TValue>([NotNull] Expression<Func<TModel, TValue>> expression)
+        public string DisplayTextFor<TValue>([NotNull] Expression<Func<TModel, TValue>> expression)
         {
             return GenerateDisplayText(GetModelMetadata(expression));
         }
@@ -144,7 +144,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <inheritdoc />
-        public HtmlString IdFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression)
+        public string IdFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression)
         {
             return GenerateId(GetExpressionName(expression));
         }
@@ -172,7 +172,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <inheritdoc />
-        public HtmlString NameFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression)
+        public string NameFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression)
         {
             var expressionName = GetExpressionName(expression);
             return Name(expressionName);
@@ -242,7 +242,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
         }
 
         /// <inheritdoc />
-        public HtmlString ValueFor<TProperty>(Expression<Func<TModel, TProperty>> expression, string format)
+        public string ValueFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression, string format)
         {
             var metadata = GetModelMetadata(expression);
             return GenerateValue(ExpressionHelper.GetExpressionText(expression), metadata.Model, format,

src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperDisplayNameExtensions.cs

@@ -8,32 +8,36 @@ using System.Linq.Expressions;
 namespace Microsoft.AspNet.Mvc.Rendering
 {
     /// <summary>
-    /// DisplayName-related extensions for <see cref="HtmlHelper"/> and <see cref="IHtmlHelper{T}"/>.
+    /// DisplayName-related extensions for <see cref="IHtmlHelper"/> and <see cref="IHtmlHelper{TModel}"/>.
     /// </summary>
     public static class HtmlHelperDisplayNameExtensions
     {
         /// <summary>
-        /// Gets the display name for the current model.
+        /// Returns the display name for the current model.
         /// </summary>
-        /// <returns>An <see cref="HtmlString"/> that represents HTML markup.</returns>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
-        public static HtmlString DisplayNameForModel([NotNull] this IHtmlHelper htmlHelper)
+        /// <returns>A <see langref="string"/> containing the display name.</returns>
+        public static string DisplayNameForModel([NotNull] this IHtmlHelper htmlHelper)
         {
             return htmlHelper.DisplayName(string.Empty);
         }
 
         /// <summary>
-        /// Gets the display name for the model.
+        /// Returns the display name for the specified <paramref name="expression"/>
+        /// if the current model represents a collection.
         /// </summary>
-        /// <param name="htmlHelper">The <see cref="IHtmlHelper{T}"/> instance that this method extends.</param>
+        /// <param name="htmlHelper">
-        /// <param name="expression">An expression that identifies the object that contains the display name.</param>
+        /// The <see cref="IHtmlHelper{IEnumerable<TModelItem>}"/> instance this method extends.
-        /// <returns>
+        /// </param>
-        /// The display name for the model.
+        /// <param name="expression">The expression to be evaluated against an item in the current model.</param>
-        /// </returns>
+        /// <typeparam name="TModelItem">The <see cref="Type"/> of items in the model collection.</typeparam>
-        public static HtmlString DisplayNameFor<TInnerModel, TValue>(
+        /// <typeparam name="TValue">The <see cref="Type"/> of the <param name="expression"> result.</typeparam>
-            [NotNull] this IHtmlHelper<IEnumerable<TInnerModel>> htmlHelper,
+        /// <returns>A <see langref="string"/> containing the display name.</returns>
-            [NotNull] Expression<Func<TInnerModel, TValue>> expression)
+        public static string DisplayNameFor<TModelItem, TValue>(
+            [NotNull] this IHtmlHelper<IEnumerable<TModelItem>> htmlHelper,
+            [NotNull] Expression<Func<TModelItem, TValue>> expression)
         {
-            return htmlHelper.DisplayNameForInnerType<TInnerModel, TValue>(expression);
+            return htmlHelper.DisplayNameForInnerType<TModelItem, TValue>(expression);
         }
     }
 }

src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperNameExtensions.cs

@@ -4,26 +4,26 @@
 namespace Microsoft.AspNet.Mvc.Rendering
 {
     /// <summary>
-    /// Name-related extensions for <see cref="HtmlHelper"/> and <see cref="HtmlHelper{T}"/>.
+    /// Name-related extensions for <see cref="IHtmlHelper"/>.
     /// </summary>
     public static class HtmlHelperNameExtensions
     {
         /// <summary>
-        /// Gets the full HTML field name for the current model.
+        /// Returns the full HTML element name for the current model.
         /// </summary>
-        /// <param name="htmlHelper">The <see cref="HtmlHelper"/> instance that this method extends.</param>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
-        /// <returns>An <see cref="HtmlString"/> that represents HTML markup.</returns>
+        /// <returns>A <see langref="string"/> containing the element name.</returns>
-        public static HtmlString NameForModel([NotNull] this IHtmlHelper htmlHelper)
+        public static string NameForModel([NotNull] this IHtmlHelper htmlHelper)
         {
             return htmlHelper.Name(string.Empty);
         }
 
         /// <summary>
-        /// Gets the full HTML field id for the current model.
+        /// Returns the HTML element Id for the current model.
         /// </summary>
-        /// <param name="htmlHelper">The <see cref="HtmlHelper"/> instance that this method extends.</param>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
-        /// <returns>An <see cref="HtmlString"/> that represents HTML markup.</returns>
+        /// <returns>A <see langref="string"/> containing the element Id.</returns>
-        public static HtmlString IdForModel([NotNull] this IHtmlHelper htmlHelper)
+        public static string IdForModel([NotNull] this IHtmlHelper htmlHelper)
         {
             return htmlHelper.Id(string.Empty);
         }

src/Microsoft.AspNet.Mvc.Core/Rendering/HtmlHelperValueExtensions.cs

@@ -6,28 +6,71 @@ using System.Linq.Expressions;
 
 namespace Microsoft.AspNet.Mvc.Rendering
 {
+    /// <summary>
+    /// Value-related extensions for <see cref="IHtmlHelper"/> and <see cref="IHtmlHelper{TModel}"/>.
+    /// </summary>
     public static class HtmlHelperValueExtensions
     {
-        public static HtmlString Value([NotNull] this IHtmlHelper htmlHelper, string name)
+        /// <summary>
+        /// Returns the formatted value for the specified expression <paramref name="name"/>.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="name">Expression name, relative to the current model.</param>
+        /// <returns>A <see langref="string"/> containing the formatted value.</returns>
+        /// <remarks>
+        /// Converts the expression <paramref name="name"/> result to a <see langref="string"/> directly.
+        /// </remarks>
+        public static string Value([NotNull] this IHtmlHelper htmlHelper, string name)
         {
             return htmlHelper.Value(name, format: null);
         }
 
-        public static HtmlString ValueFor<TModel, TProperty>(
+        /// <summary>
+        /// Returns the formatted value for the specified <paramref name="expression"/>.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper{TModel}"/> instance this method extends.</param>
+        /// <param name="expression">The expression to be evaluated against the current model.</param>
+        /// <typeparam name="TModel">The <see cref="Type"/> of the model.</typeparam>
+        /// <typeparam name="TProperty">The <see cref="Type"/> of the <param name="expression"> result.</typeparam>
+        /// <returns>A <see langref="string"/> containing the formatted value.</returns>
+        /// <remarks>
+        /// Converts the <paramref name="expression"/> result to a <see langref="string"/> directly.
+        /// </remarks>
+        public static string ValueFor<TModel, TProperty>(
             [NotNull] this IHtmlHelper<TModel> htmlHelper,
             [NotNull] Expression<Func<TModel, TProperty>> expression)
         {
             return htmlHelper.ValueFor(expression, format: null);
         }
 
-        public static HtmlString ValueForModel([NotNull] this IHtmlHelper htmlHelper)
+        /// <summary>
+        /// Returns the formatted value for the current model.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <returns>A <see langref="string"/> containing the formatted value.</returns>
+        /// <remarks>
+        /// Converts the model value to a <see langref="string"/> directly.
+        /// </remarks>
+        public static string ValueForModel([NotNull] this IHtmlHelper htmlHelper)
         {
-            return ValueForModel(htmlHelper, format: null);
+            return htmlHelper.Value(name: string.Empty, format: null);
         }
 
-        public static HtmlString ValueForModel([NotNull] this IHtmlHelper htmlHelper, string format)
+        /// <summary>
+        /// Returns the formatted value for the current model.
+        /// </summary>
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <param name="format">
+        /// The composite format <see langref="string"/> (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx).
+        /// </param>
+        /// <returns>A <see langref="string"/> containing the formatted value.</returns>
+        /// <remarks>
+        /// Converts the model value to a <see langref="string"/> directly if
+        /// <paramref name="format"/> is <see langref="null"/> or empty.
+        /// </remarks>
+        public static string ValueForModel([NotNull] this IHtmlHelper htmlHelper, string format)
         {
-            return htmlHelper.Value(string.Empty, format);
+            return htmlHelper.Value(name: string.Empty, format: format);
         }
     }
 }

src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelper.cs

@@ -146,23 +146,21 @@ namespace Microsoft.AspNet.Mvc.Rendering
             object additionalViewData);
 
         /// <summary>
-        /// Gets the display name.
+        /// Returns the display name for the specified expression <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">An expression that identifies the object that contains the display name.</param>
+        /// <param name="expression">Expression name, relative to the current model.</param>
-        /// <returns>
+        /// <returns>A <see langref="string"/> containing the display name.</returns>
-        /// The display name.
+        string DisplayName(string expression);
-        /// </returns>
-        HtmlString DisplayName(string expression);
 
-        /// Returns the HtmlString corresponding to the property in the model specified by the name.
+        /// <summary>
+        /// Returns the simple display text for the specified expression <paramref name="name"/>.
         /// </summary>
-        /// <param name="name">
+        /// <param name="name">Expression name, relative to the current model.</param>
-        /// The string which identifies the object for which the HtmlString should be returned.</param>
         /// <returns>
-        /// New <see cref="HtmlString"/> containing the display text. If the value is null,
+        /// A <see langref="string"/> containing the simple display text.
-        /// then it returns the ModelMetadata.NullDisplayText.
+        /// If the expression result is <see langref="null"/>, returns <see cref="ModelMetadata.NullDisplayText"/>.
         /// </returns>
-        HtmlString DisplayText(string name);
+        string DisplayText(string name);
 
         /// <summary>
         /// Returns a single-selection HTML {select} element using the specified name of the form field,
@@ -263,11 +261,11 @@ namespace Microsoft.AspNet.Mvc.Rendering
         HtmlString Hidden(string name, object value, object htmlAttributes);
 
         /// <summary>
-        /// Gets the Id of the given string.
+        /// Returns the HTML element Id for the specified expression <paramref name="name"/>.
         /// </summary>
-        /// <param name="name">The string which identifies the object for which the Id should be returned.</param>
+        /// <param name="name">Expression name, relative to the current model.</param>
-        /// <returns>New <see cref="HtmlString"/> containing the Id.</returns>
+        /// <returns>A <see langref="string"/> containing the element Id.</returns>
-        HtmlString Id(string name);
+        string Id(string name);
 
         /// <summary>
         /// Returns an HTML label element and the property name of the property that is represented by the specified
@@ -295,11 +293,11 @@ namespace Microsoft.AspNet.Mvc.Rendering
         HtmlString ListBox(string name, IEnumerable<SelectListItem> selectList, object htmlAttributes);
 
         /// <summary>
-        /// Gets the full HTML field name for the given expression <paramref name="name"/>.
+        /// Returns the full HTML element name for the specified expression <paramref name="name"/>.
         /// </summary>
-        /// <param name="name">Name of an expression, relative to the current model.</param>
+        /// <param name="name">Expression name, relative to the current model.</param>
-        /// <returns>An <see cref="HtmlString"/> that represents HTML markup.</returns>
+        /// <returns>A <see langref="string"/> containing the element name.</returns>
-        HtmlString Name(string name);
+        string Name(string name);
 
         /// <summary>
         /// Returns a partial view in string format.
@@ -472,11 +470,17 @@ namespace Microsoft.AspNet.Mvc.Rendering
             string tag);
 
         /// <summary>
-        /// Returns the model value for the given expression <paramref name="name"/>.
+        /// Returns the formatted value for the specified expression <paramref name="name"/>.
         /// </summary>
-        /// <param name="name">Name of an expression, relative to the current model.</param>
+        /// <param name="name">Expression name, relative to the current model.</param>
-        /// <param name="format">The optional format string to apply to the value.</param>
+        /// <param name="format">
-        /// <returns>An <see cref="HtmlString"/> that represents HTML markup.</returns>
+        /// The composite format <see langref="string"/> (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx).
-        HtmlString Value([NotNull] string name, string format);
+        /// </param>
+        /// <returns>A <see langref="string"/> containing the formatted value.</returns>
+        /// <remarks>
+        /// Converts the expression result to a <see langref="string"/> directly if
+        /// <paramref name="format"/> is <see langref="null"/> or empty.
+        /// </remarks>
+        string Value([NotNull] string name, string format);
     }
 }

src/Microsoft.AspNet.Mvc.Core/Rendering/IHtmlHelperOfT.cs

@@ -10,7 +10,7 @@ namespace Microsoft.AspNet.Mvc.Rendering
     /// <summary>
     /// An <see cref="IHtmlHelper"/> for Linq expressions.
     /// </summary>
-    /// <typeparam name="TModel">The <see cref="Type"/> of the model.</typeparam>
+    /// <typeparam name="TModel">The type of the model.</typeparam>
     public interface IHtmlHelper<TModel> : IHtmlHelper
     {
         /// <summary>
@@ -54,36 +54,35 @@ namespace Microsoft.AspNet.Mvc.Rendering
                                       object additionalViewData);
 
         /// <summary>
-        /// Gets the display name for the model.
+        /// Returns the display name for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">An expression that identifies the object that contains the display name.</param>
+        /// <param name="expression">The expression to be evaluated against the current model.</param>
-        /// <typeparam name="TValue">The type of the value.</typeparam>
+        /// <typeparam name="TValue">The type of the <param name="expression"> result.</typeparam>
-        /// <returns>
+        /// <returns>A <see langref="string"/> containing the display name.</returns>
-        /// The display name for the model.
+        string DisplayNameFor<TValue>([NotNull] Expression<Func<TModel, TValue>> expression);
-        /// </returns>
-        HtmlString DisplayNameFor<TValue>([NotNull] Expression<Func<TModel, TValue>> expression);
 
         /// <summary>
-        /// Gets the display name for the inner model if the current model represents a collection.
+        /// Returns the display name for the specified <paramref name="expression"/>
+        /// if the current model represents a collection.
         /// </summary>
-        /// <typeparam name="TInnerModel">The type of the inner model</typeparam>
+        /// <param name="expression">The expression to be evaluated against an item in the current model.</param>
-        /// <typeparam name="TValue">The type of the value.</typeparam>
+        /// <typeparam name="TModelItem">The type of items in the model collection.</typeparam>
-        /// <param name="expression">An expression that identifies the object that contains the display name.</param>
+        /// <typeparam name="TValue">The type of the <param name="expression"> result.</typeparam>
-        /// <returns>The display name for the inner model.</returns>
+        /// <returns>A <see langref="string"/> containing the display name.</returns>
-        HtmlString DisplayNameForInnerType<TInnerModel, TValue>(
+        string DisplayNameForInnerType<TModelItem, TValue>(
-            [NotNull] Expression<Func<TInnerModel, TValue>> expression);
+            [NotNull] Expression<Func<TModelItem, TValue>> expression);
 
         /// <summary>
-        /// Returns the HtmlString corresponding to the expression specified.
+        /// Returns the simple display text for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">
+        /// <param name="expression">The expression to be evaluated against the current model.</param>
-        /// The expression identifies the object for which the HtmlString should be returned.
+        /// <typeparam name="TValue">The type of the <param name="expression"> result.</typeparam>
-        /// </param>
         /// <returns>
-        /// New <see cref="HtmlString"/> containing the display text. If the value is null,
+        /// A <see langref="string"/> containing the simple display text.
-        /// then it returns the ModelMetadata.NullDisplayText.
+        /// If the <param name="expression"> result is <see langref="null"/>, returns
+        /// <see cref="ModelMetadata.NullDisplayText"/>.
         /// </returns>
-        HtmlString DisplayTextFor<TValue>([NotNull] Expression<Func<TModel, TValue>> expression);
+        string DisplayTextFor<TValue>([NotNull] Expression<Func<TModel, TValue>> expression);
 
         /// <summary>
         /// Returns a single-selection HTML {select} element for the object that is represented
@@ -141,11 +140,12 @@ namespace Microsoft.AspNet.Mvc.Rendering
             object htmlAttributes);
 
         /// <summary>
-        /// Gets the Id of the given expression.
+        /// Returns the HTML element Id for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">The expression identifies the object for which the Id should be returned.</param>
+        /// <param name="expression">The expression to be evaluated against the current model.</param>
-        /// <returns>New <see cref="HtmlString"/> containing the Id.</returns>
+        /// <typeparam name="TProperty">The type of the <param name="expression"> result.</typeparam>
-        HtmlString IdFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression);
+        /// <returns>A <see langref="string"/> containing the element Id.</returns>
+        string IdFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression);
 
         /// <summary>
         /// Returns an HTML label element and the property name of the property that is represented by the specified
@@ -180,12 +180,12 @@ namespace Microsoft.AspNet.Mvc.Rendering
             object htmlAttributes);
 
         /// <summary>
-        /// Gets the full HTML field name for the given <paramref name="expression"/>.
+        /// Returns the full HTML element name for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <typeparam name="TProperty">The <see cref="Type"/> the <paramref name="expression"/> returns.</typeparam>
+        /// <param name="expression">The expression to be evaluated against the current model.</param>
-        /// <param name="expression">An expression, relative to the current model.</param>
+        /// <typeparam name="TProperty">The type of the <paramref name="expression"/> result.</typeparam>
-        /// <returns>An <see cref="HtmlString"/> that represents HTML markup.</returns>
+        /// <returns>A <see langref="string"/> containing the element name.</returns>
-        HtmlString NameFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression);
+        string NameFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression);
 
         /// <summary>
         /// Render an input element of type "password".
@@ -262,11 +262,18 @@ namespace Microsoft.AspNet.Mvc.Rendering
             string tag);
 
         /// <summary>
-        /// Returns the model value for the given expression <paramref name="expression"/>.
+        /// Returns the formatted value for the specified <paramref name="expression"/>.
         /// </summary>
-        /// <param name="expression">An expression, relative to the current model.</param>
+        /// <param name="expression">The expression to be evaluated against the current model.</param>
-        /// <param name="format">The optional format string to apply to the value.</param>
+        /// <param name="format">
-        /// <returns>An <see cref="HtmlString"/> that represents HTML markup.</returns>
+        /// The composite format <see langref="string"/> (see http://msdn.microsoft.com/en-us/library/txafckwd.aspx).
-        HtmlString ValueFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression, string format);
+        /// </param>
+        /// <typeparam name="TProperty">The type of the <param name="expression"> result.</typeparam>
+        /// <returns>A <see langref="string"/> containing the formatted value.</returns>
+        /// <remarks>
+        /// Converts the <paramref name="expression"/> result to a <see langref="string"/> directly if
+        /// <paramref name="format"/> is <see langref="null"/> or empty.
+        /// </remarks>
+        string ValueFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>> expression, string format);
     }
 }