Ошибка в документации XML после добавления кода примера

Question

Я пытаюсь написать документацию для API, который я написал. Компилятор C# не создает документацию для этого конкретного метода. В нем говорится, что документация XML плохо сформирована.

Не могли бы вы помочь мне определить, где он плохо сформирован? Я проверил код много раз, и я просто не могу найти проблему. К сожалению, компилятор C# не скажет мне, какая строка вызывает проблему.

/// <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

В этой строке

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

использовать & без возможности избежать этого, как &. В XML простая & обозначает начало character reference. Следующие исправления ваша проблема:

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

---

Debugging подсказка: Удалите строки и перекомпилировать, пока проблема не исчезнет. Если вы do that smartly, вы найдете оскорбительную строку в O(log n) шагах. Вот как я нашел проблему. Это относится не только к документации XML, но также ко всем другим случаям, когда сообщение об ошибке не указывает строку нарушения.