Почему генератор XML документации C # не работает правильно для импортированных из COM интерфейсов? - PullRequest
Новая
       33

Почему генератор XML документации C # не работает правильно для импортированных из COM интерфейсов?

1 голос
/ 28 марта 2012

При использовании комментариев к документации 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
    {
    }
}

приводит к tон следует следующему фрагменту файла документации 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?

Ответы [ 2 ]

1 голос
/ 29 марта 2012

Действительно интересный вопрос. Я мог бы воспроизвести это, но для ParagraphFormatClass.Alignment это все еще неправильно для меня. Что еще интереснее, если вы на самом деле используете эти элементы в своем коде (в данном методе) даже в блоке if (false), ссылки XML cref разрешаются правильно. Но, к сожалению, этот прием работает только в методах, а не в классах. Поэтому я думаю, что у вас нет выбора, кроме как вручную ввести идентификаторы ссылки на член: 

<see cref="M:Microsoft.Office.Interop.Word._Document.Activate"/>

<see cref="P:Microsoft.Office.Interop.Word._Document.ActiveTheme"/>
0 голосов
/ 30 марта 2012

Это приложение .NET 4.0? Если это так, это может быть вызвано компилятором, использующим динамические типы за кулисами. Если ваш проект содержит ссылку на Microsoft.CSharp, это указывает на возможность использования динамических типов. Если вы удалите ссылку и выполните сборку, вы получите ошибки компилятора о невозможности разрешить типы, необходимые для динамического кода, если это так. Выполнение этого в моих проектах надстроек помечает случаи, когда я использую Document и несколько других типов, как требующие динамических типов связывателя. Возможно, именно поэтому компилятор разрешает члены класса, но не интерфейсы. В случаях, когда используются динамические типы, они не будут разрешены до времени выполнения. Таким образом, компилятору нечего использовать для идентификатора члена XML-комментариев. В любом случае, это моя теория.

...