Recupera commenti di documenti xml a livello di codice [chiuso]

Question

Visual Studio lo fa; Reflector lo fa; e ora lo voglio anche io :)

Desidero recuperare la documentazione XML per alcuni membri in alcuni assiemi di framework (ovvero mscorlib.dll, System.dll, ecc.). Presumo che ciò implicherebbe:

• ricerca del file XML per l'assembly,
• navigando verso l'elemento figlio con il nome appropriato e
• recupero degli elementi desiderati (<summary>, <remarks>, ecc.)

Dove sono conservati i file XML per gli assembly framework? Qualche punto sulla decifrazione dello schema di denominazione XMLDOC? Esistono librerie che renderanno questo processo più semplice?

Answer 1

Trova xml

Per assembly.dll è denominato assembly.xml, ma installato da Framework SDK, il runtime stesso non contiene file .xml. Gli utenti non hanno bisogno della documentazione API.

La posizione è un po 'più complessa. Può essere affiancato alla DLL, nella sottodirectory che prende il nome dalla locale corrente (ad es. C: \ WINDOWS \ Microsoft.NET \ Framework \ v2.0.50727 \ en) o anche in qualche strana directory nelle vicinanze. Suggerirei di cercarlo nel modo in cui il runtime cerca gli assemblaggi satellitari.

Trova elemento

Per trovare l'elemento, dovresti preparare il cosiddetto " ID xml-doc " dai metadati. AFAIR è documentato nelle specifiche del linguaggio C # e un po 'in MSDN. Vedi Elaborazione della documentazione XML .

Answer 2

Basato su Risposta di Ilya :

Trova xml

Posizioni di fallback .NET (ignorando GAC e altri sottodirectory irrilevanti)

static FileInfo GetXmlDocFile( Assembly assembly ) {
  string assemblyDirPath = Path.GetDirectoryName( assembly.Location );
  string fileName = Path.GetFileNameWithoutExtension( assembly.Location ) +".xml";

  return GetFallbackDirectories( CultureInfo.CurrentCulture )
    .Select( dirName => CombinePath( assemblyDirPath, dirName, fileName ) )
    .Select( filePath => new FileInfo( filePath ) )
    .Where( file => file.Exists )
    .First( );
}

static IEnumerable<string> GetFallbackDirectories( CultureInfo culture ) {
  return culture
    .Enumerate( c => c.Parent.Name != c.Name ? c.Parent : null )
    .Select( c => c.Name );
}

static IEnumerable<T> Enumerate<T>( this T start, Func<T, T> next ) {
  for( T item = start; !object.Equals( item, default(T) ); item = next( item ) )
    yield return item;
}

static string CombinePath( params string[] args ) {
  return args.Aggregate( Path.Combine );
}

Trova elemento

Elaborazione della documentazione XML

static XElement GetDocMember( XElement docMembers, MemberInfo member ) {
  string memberId = GetMemberId( member );
  return docMembers.Elements( "member" )
    .Where( e => e.Attribute( "name" ).Value == memberId )
    .First( );
}

static string GetMemberId( MemberInfo member ) {
  char memberKindPrefix = GetMemberPrefix( member );
  string memberName = GetMemberFullName( member );
  return memberKindPrefix + ":" + memberName;
}

static char GetMemberPrefix( MemberInfo member ) {
  return member.GetType( ).Name
    .Replace( "Runtime", "" )[0];
}

static string GetMemberFullName( MemberInfo member ) {
  string memberScope = "";
  if( member.DeclaringType != null )
    memberScope = GetMemberFullName( member.DeclaringType );
  else if( member is Type )
    memberScope = ((Type)member).Namespace;

  return memberScope + "." + member.Name;
}

Esempio di utilizzo

Type type = typeof( string );

var file = GetXmlDocFile( type.Assembly );
var docXml = XDocument.Load( file.FullName );
var docMembers = docXml.Root.Element( "members" );

var member = type.GetProperty( "Length" );
var docMember = GetDocMember( docMembers, member );

Answer 3

Mantengo il progetto Jolt.NET su CodePlex e ho implementato una funzione che svolge proprio questo compito. Per ulteriori informazioni, consultare la Jolt per ulteriori informazioni.

In sostanza, la libreria consente di individuare e interrogare in modo programmatico un file di commenti di documenti XML per un assembly utilizzando i tipi di metadati in System.Reflection (ovvero MethodInfo, PropertyInfo, ecc ...).

Answer 4

Prova DocsByReflection .

// From method.
var methodInfo = typeof(Stub).GetMethod("MethodWithGenericParameter");
var methodDoc = DocsService.GetXmlFromMember(methodInfo);

Answer 5

Ecco una libreria pronta che ti consentirà di fare proprio questo: NuDoc http://kzu.to/nudoc

Leggere l'intera documentazione su mscorlib, ad esempio, sarebbe semplice come:

var members = Reader.Read(typeof(string).Assembly);

E in seguito puoi elaborare i risultati usando un semplice visitatore, come mostrato sul sito.

Sono in procinto di sfruttare quella libreria per generare un sito API usando il markdown per l'hosting in GitHub, idealmente automaticamente su ogni build, e forse anche per il wiki in modo che possa essere aggiornato e reinserito nel codice :) .

Answer 6

Il file XML è chiamato esattamente come il file dell'assembly, ad eccezione della diversa estensione 'xml' e deve trovarsi nella stessa directory dell'assembly stesso.

Tuttavia, non posso aiutarti con le altre due domande. AFAIK, sei da solo ...