@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 @@ public string GenerateIdFromName([NotNull] string name)
         }
 
         /// <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 @@ public HtmlString Hidden(string name, object value, object htmlAttributes)
         }
 
         /// <inheritdoc />
-        public HtmlString Id(string name)
+        public string Id(string name)
         {
             return GenerateId(name);
         }
@@ -318,7 +317,7 @@ public HtmlString ListBox(string name, IEnumerable<SelectListItem> selectList, o
         }
 
         /// <inheritdoc />
-        public HtmlString Name(string name)
+        public string Name(string name)
         {
             return GenerateName(name);
         }
@@ -484,7 +483,7 @@ public HtmlString TextBox(string name, object value, string format, IDictionary<
         }
 
         /// <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 @@ protected object GetModelStateValue(string key, Type destinationType)
                 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 @@ protected virtual HtmlString GenerateDisplayName([NotNull] ModelMetadata metadat
                     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 @@ protected virtual HtmlString GenerateDisplayText(ModelMetadata metadata)
                 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 @@ protected virtual HtmlString GenerateId(string expression)
                 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 @@ protected virtual HtmlString GenerateName(string name)
             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 @@ protected virtual HtmlString GenerateValue(string name, object value, string for
                 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 @@ public override void Contextualize([NotNull] ViewContext viewContext)
         }
 
         /// <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>(
-            [NotNull] Expression<Func<TInnerModel, TValue>> expression)
+        public string DisplayNameForInnerType<TModelItem, TValue>(
+            [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 @@ public HtmlString DisplayNameFor<TValue>([NotNull] Expression<Func<TModel, TValu
         }
 
         /// <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 @@ public HtmlString DisplayTextFor<TValue>([NotNull] Expression<Func<TModel, TValu
         }
 
         /// <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 @@ public HtmlString IdFor<TProperty>([NotNull] Expression<Func<TModel, TProperty>>
         }
 
         /// <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 @@ protected ModelMetadata GetModelMetadata<TProperty>([NotNull] Expression<Func<TM
         }
 
         /// <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 @@
 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>
-        public static HtmlString DisplayNameForModel([NotNull] this IHtmlHelper htmlHelper)
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <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="expression">An expression that identifies the object that contains the display name.</param>
-        /// <returns>
-        /// The display name for the model.
-        /// </returns>
-        public static HtmlString DisplayNameFor<TInnerModel, TValue>(
-            [NotNull] this IHtmlHelper<IEnumerable<TInnerModel>> htmlHelper,
-            [NotNull] Expression<Func<TInnerModel, TValue>> expression)
+        /// <param name="htmlHelper">
+        /// The <see cref="IHtmlHelper{IEnumerable<TModelItem>}"/> instance this method extends.
+        /// </param>
+        /// <param name="expression">The expression to be evaluated against an item in the current model.</param>
+        /// <typeparam name="TModelItem">The <see cref="Type"/> of items in the model collection.</typeparam>
+        /// <typeparam name="TValue">The <see cref="Type"/> of the <param name="expression"> result.</typeparam>
+        /// <returns>A <see langref="string"/> containing the display name.</returns>
+        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>
-        /// <returns>An <see cref="HtmlString"/> that represents HTML markup.</returns>
-        public static HtmlString NameForModel([NotNull] this IHtmlHelper htmlHelper)
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <returns>A <see langref="string"/> containing the element name.</returns>
+        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>
-        /// <returns>An <see cref="HtmlString"/> that represents HTML markup.</returns>
-        public static HtmlString IdForModel([NotNull] this IHtmlHelper htmlHelper)
+        /// <param name="htmlHelper">The <see cref="IHtmlHelper"/> instance this method extends.</param>
+        /// <returns>A <see langref="string"/> containing the element Id.</returns>
+        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 @@
 
 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);
         }
     }
 }