Error in XML documentation after adding sample code [closed]

Question

Closed. This question needs details or clarity. It is not currently accepting answers.

---

Want to improve this question? Add details and clarify the problem by editing this post.

Closed 8 years ago.

Improve this question

I am trying to write some documentation for an API I wrote. The C# compiler does not generate documentation for this particular method. It says that the XML documentation is ill-formed.

Could you please help me identify where it is ill-formed? I have checked the code many times, and I just cannot find the problem. Unfortunately, the C# compiler won't tell me which line is causing the problem.

/// <summary>
/// Given a value pertaining to a specific culture, let's call it the value culture, 
/// this method returns a sequence of resource keys and their values in another culture, 
/// let's call this the desired culture, based on a search of matching values in the value culture. 
/// The search can further be filtered based on metadata.
/// </summary>
/// <typeparam name="T">Represents the System.Type of value to look up and return.</typeparam>
/// <param name="value">The value pertaining to a value culture to search for.</param>
/// <param name="valueCulture">The short name of the culture to which the value specified by the <paramref name="value"/> parameter belongs.</param>
/// <param name="desiredCulture">The short name of the culture in which matching resource keys and values are to be sought.</param>
/// <param name="metadata">Metadata to filter the search results with.</param>
/// <param name="defaultValue">A default value to be returned if no matching records are found.</param>
/// <returns>Returns an object of <see cref = "ReverseLookupResult{T}"/>, which contains all the search parameters and a sequence of matches.</returns>
/// <remarks>
/// <para>One of the most common scenarios when implementing internationalization in your software is this.</para>
/// 
/// <para>The application you want to internationalize has already been developed. Or at least a 
/// significant part of it has been developed and work is ongoing, and amidst the chaos, you 
/// have been asked to internationalize string resources.</para>
/// 
/// <para>In this scenario, you already have English strings in your application. It would be so much nicer and easier for you 
/// did not have remember resource keys but simply call a method to which you gave an English value and it gave you back the 
/// equivalent value in another culture of your choice. For e.g. if you wanted to translate your software into French, it would 
/// be so much nicer if you simply supplied to a method the value "Hello" in English and it returned to you "Bonjour". That way, 
/// you could simply call that method wherever the English strings were in your application without having to remember resource keys.</para>
/// 
/// <para>This is the primary need that this method fulfills.</para>
/// 
/// <example>
/// Consider this example. Suppose you had a program like so:
/// 
/// <code>
/// public void PrintMessage()
/// {
///     System.Console.WriteLine("Hello");
/// }
/// </code>
/// </example>
/// 
/// <example>
/// And you were asked to internatlize it to support French. You would use this method like so:
/// 
/// <code>
/// private string _desiredCulture = "fr-FR";
/// 
/// public void PrintMessage()
/// {
///     ResourceManager resourceManager = new ResourceManager("en-US");
///     
///     var reverseLookupResult = resourceManager.ReverseLookup("Hello", "en-US", 
///                                                 _desiredCulture, null, "Hello");
///                                                 
///     if (reverseLookupResult != null && reverseLookupResult.Matches.Count > 0)
///     {
///         System.Console.WriteLine(reverseLookupResult.Matches.First().Value);
///     }
/// }
/// </code>
/// </example>
/// 
/// </remarks>
public ReverseLookupResult<T> ReverseLookup<T>(T value, string valueCulture, string desiredCulture,
    IMetadata metadata, T defaultValue = default(T))

Answer 1

In this line

///     if (reverseLookupResult != null && reverseLookupResult.Matches.Count > 0)

you use & without escaping it as &. In XML, a plain & denotes the start of a character reference. The following fixes your problem:

///     if (reverseLookupResult != null && reverseLookupResult.Matches.Count > 0)

---

Debugging hint: Remove lines and recompile until the problem disappears. If you do that smartly, you will find the offending line in O(log n) steps. This is how I found the problem. This does not only apply to XML documentation but also to all other cases where the error message does not specify the offending line.