Пример кода XML документации Sandcastle без возврата каретки - PullRequest
Новая
       25

Пример кода XML документации Sandcastle без возврата каретки

2 голосов
/ 21 марта 2012

Я использую sandcastle для документирования в API веб-службы, а также для сводок и замечаний к пространству имен верхнего уровня. Я добавил файл sandcastle.xml в свой проект.

Моя проблема заключается в том, что я пытаюсь добавить пример кода xml в раздел примечаний пространства имен в этом файле XML. Sandcastle отображает код xml на одной строке без возврата каретки. 

<member name="N:BrokerServices.GatewayAsmx">
    <summary>summary text</summary>
    <remarks>
        remarks text
        <example>
               Sample xml code              
               <code lang="xml">
                <Membership>
                    <firstname>Cliff</firstname>
                    <lastname>Mayson</lastname>
                    <age>27</age>
                </Membership>
            </code>
        </example>
    </remarks>
</member>

В результате приведенный пример кода отображается следующим образом: 

<Member><firstname>Cliff</firstname><lastname>Mayson</lastname><age>27</age></Member>

Я пытался использовать \ n или \ r, которые работают, но символы \ n и \ r остались в примере кода: 

<Member><firstname>Cliff</firstname>\n
    <lastname>Mayson</lastname>\n
    <age>27</age>\r
</Member>

Как вставить новые строки без отображения символов новой строки в коде.

Ответы [ 2 ]

3 голосов
/ 21 марта 2012

Если языковым атрибутом тега code является xml, необходимо добавить атрибут xml: space = "preserve" в тег для примера xml для правильной визуализации.

например. 

<member name="N:BrokerServices.GatewayAsmx">
    <summary>summary text</summary>
    <remarks>
        remarks text 
    </remarks>
    <example>
        Sample xml code             
        <code lang="xml" xml:space="preserve">
            <Membership>
                <firstname>Cliff</firstname>
                <lastname>Mayson</lastname>
                <age>27</age>
            </Membership>
        </code>
    </example>
</member>

В этом нет необходимости, если значение атрибута lang тега code равно c # или VB

3 голосов
/ 21 марта 2012

1-й вариант: заменить символы < на &lt;.
2-й вариант: поместить свой XML-код в блок <![CDATA[ ... ]]>.
3-й вариант: вы также можете использовать альтернативный инструмент, такой как ForgeDoc :)

Еще одна вещь: не помещайте блоки примеров в раздел замечаний.Example - это тег верхнего уровня.

...