Comentários XML - As referências devem ser totalmente qualificadas?

Question

Basicamente, quando é realmente necessário (se é que é necessário) usar um xml totalmente qualificado, consulte a referência:

<see cref="T:MyNamespace.Sub.MyType"/> //Option 1
<see cref="T:MyType"> //Option 2

Além disso, que tal fazer referência aos objetos do .NET Framework?

<see cref="T:System.Collections.Generic.ICollection{T}"/> //Option 1
<see cref="T:ICollection{T}"/> //Option 2

Entendo que os itens totalmente qualificados sempre permitirão que o Sandcastle da Microsoft vincule as coisas corretamente, mas é necessário que tudo seja totalmente qualificado?

---

Nota:O Microsoft Sandcastle poderá vincular-se aos arquivos de ajuda do .NET Framework ou estou perdendo meu tempo fazendo referência <see cref="T:System.Collections.Generic.ICollection{T}"/>?

Answer 1

Ambos Joseph e Bem abordarei pontos úteis, mas acho que minha experiência recente no Sandcastle pode ser útil:

1. Quando você compila seu projeto, o Visual Studio normalmente lhe dirá imediatamente se sua referência é válida, emitindo um aviso se não puder resolver uma referência em seus comentários de documento, se esta é uma referência aos seus próprios tipos ou aos tipos de sistema (e o VS faz isso). honre suas declarações de "uso").

2. No cenário de ter um tipo local mascarando um tipo de sistema, há dois casos a serem considerados:sua assinatura qualifica exclusivamente seu tipo (abordado por (1) acima) ou sua assinatura duplica exatamente um tipo de sistema.O último caso requer desambiguação explícita através da qualificação completa do nome.

3. Você abordou o uso de especificar explicitamente o prefixo do tipo de membro (por exemplo."T:SuperWidget"), mas isso é mais significativo do que a maioria das pessoas imagina:se você usar um prefixo de tipo de membro, então nomes totalmente qualificados é requerido.Na verdade, isso está documentado no MSDN, mas no muito letras miúdas - veja Processando o arquivo XML.E para piorar a situação, se você omitir o nome totalmente qualificado, obterá nenhum aviso em tempo de construção(!);simplesmente nenhum link é gerado na renderização final do Sandcastle.Existem outros problemas se você especificar explicitamente um prefixo de tipo de membro - consulte o Desambiguando e resolvendo referências seção do meu artigo sobre dicas práticas sobre Sandcastle, Domando o Castelo de Areia:Guia do programador .NET para documentar seu código.

Answer 2

Não posso falar pelo Sandcastle, mas com base na minha experiência com outras ferramentas, por exemplo.ReSharper, parece que um tipo precisa ser qualificado se a) não estiver no escopo ou b) estiver oculto por outro tipo que seja definido mais localmente.

Em outras palavras, se você estiver using System.Collections.Generic, então você não precisará se qualificar ICollection{T}.Se acontecer de você definir o seu próprio ICollection{T} interface no mesmo arquivo, no entanto, você vai tenho que qualificar o primeiro (assim como o último, pensando bem).

Answer 3

Você não está perdendo seu tempo em <see cref />-ing the Framework, na minha opinião.O provedor de ajuda do Visual Studio deve ser capaz de interceptar e interpretar em tempo de execução quando a chamada for feita para esse tópico de ajuda.Não o usei recentemente, mas funcionou muito bem no passado.

Quanto à qualificação total, não é necessária na maioria dos cenários, mas depende do seu uso, como Ben mencionou.Contanto que o que você está referenciando esteja no escopo (e deveria estar, já que você provavelmente o usará se estiver fazendo referência a ele, ou você deve adicionar o uso para que seu código não use o formato totalmente qualificado), apenas o tipo deve ser suficiente.