При использовании комментариев XML-документации в C# для создания XML-файла документации в VS2010 SP1 я заметил, что он не работает должным образом в одном конкретном случае: для членов интерфейса, импортированных из COM. > (методы и свойства).
Давайте возьмем этот файл C#, взяв в качестве примера некоторые типы из первичной сборки взаимодействия MS Word (которая, я думаю, широко известна большинству людей):
using Microsoft.Office.Interop.Word;
namespace TestProject
{
/// <summary>
/// Documentation test class. This documentation references a COM interface: <see cref="_Document"/>
/// and a method in that interface: <see cref="_Document.Activate"/>, as well as a property
/// <see cref="_Document.ActiveTheme"/>.
/// </summary>
public class DocumentedClass
{
}
}
Полученный файл документации .XML содержит следующее:
<member name="T:TestProject.DocumentedClass">
<summary>
Documentation test class. This documentation references a COM interface: <see cref="T:Microsoft.Office.Interop.Word._Document"/>
and a method in that interface: <see cref="!:_Document.Activate"/>, as well as a property
<see cref="!:_Document.ActiveTheme"/>.
</summary>
</member>
Если вы внимательно посмотрите на сгенерированный фрагмент XML-файла, то увидите, что ссылка на COM-интерфейс разрешена (T:Microsoft.Office.Interop.Word._Document), но не разрешена для членов интерфейса (например, !:_Document.Activate).
Я попытался полностью квалифицировать элементы интерфейса в комментариях к документации следующим образом, но результат тот же:
namespace TestProject
{
/// <summary>
/// Documentation test class. This documentation references
/// a COM interface: <see cref="Microsoft.Office.Interop.Word._Document"/>
/// and a method in that interface: <see cref="Microsoft.Office.Interop.Word._Document.Activate"/>,
/// as well as a property: <see cref="Microsoft.Office.Interop.Word._Document.ActiveTheme"/>.
/// </summary>
public class DocumentedClass2
{
}
}
Теперь странно то, что это, кажется, работает для COM-импортированных членов класса, например. эта документация:
using Microsoft.Office.Interop.Word;
namespace TestProject
{
/// <summary>
/// Now, let's reference a COM class <see cref="ParagraphFormatClass"/> and its member property
/// <see cref="ParagraphFormatClass.Alignment"/>.
/// </summary>
public class DocumentedClass3
{
}
}
приводит к следующему фрагменту файла XML-документации:
<member name="T:TestProject.DocumentedClass3">
<summary>
Now, let's reference a COM class <see cref="T:Microsoft.Office.Interop.Word.ParagraphFormatClass"/> and its member
<see cref="P:Microsoft.Office.Interop.Word.ParagraphFormatClass.Alignment"/>.
</summary>
</member>
что совершенно верно, поскольку свойство класса COM правильно разрешается в P:Microsoft.Office.Interop.Word.ParagraphFormatClass.Alignment.
Это действительно происходит только для COM-импортированных интерфейсов, обычные члены интерфейса правильно ссылаются в результирующих XML-файлах документации. Не имеет значения, получен ли COM-импортированный интерфейс из PIA или вы сами импортируете библиотеку типов через tlbimp.exe.
У меня такой вопрос: есть ли причина такого поведения или это ошибка? Что я могу сделать, чтобы импортированные COM-члены интерфейса правильно ссылались в сгенерированных файлах XML-документации?
