20

xml コメントを使用して、コンポーネントのパブリック メンバーと内部メンバーおよびプライベート メンバーを文書化しています。最終製品で Visual Studio Intellisense を "リッチ" (メソッド、例外、パラメーターの説明など) にできるようにするために、生成されたドキュメント xml ファイルをコンポーネント アセンブリと共にパッケージ化したいと考えています。問題は、C# コンパイラがすべてのドキュメント エントリ (内部クラス、メソッド、内部列挙型のプライベート フィールドなどを含む) を作成し、「パブリック メンバーのみ」モードへの切り替えがないように見えることです。

今は、それぞれに XX メソッドを含む 50 個を超えるファイルにアクセスして、プライベート メンバーと内部メンバーのすべてのコメントを削除したくありません。たとえそれを行ったとしても、自動生成されたリソース ファイルではあまり成功しないでしょう。これらの厳密に型指定されたリソース クラスは自動的にコメント化され、公開されないからです。

私の質問は: 私が見落としているオプション/フラグはありますか? いいえの場合、(コードを書き始める前に) パブリック メンバーを残りから分離するのに役立つツールはありますか?

4

6 に答える 6

7

SandCastle Help File Builderには、メソッド、プロパティなどに構成されたアクセスモードのみを含むxmlファイルを再作成するオプションがあります。

唯一の「欠点」は、ドキュメントを生成する必要があることです。

編集

ずっと前のことなので、XMLを生成するためにSHFBに「コンポーネント」を追加したことを忘れていました。

幸いなことに、このコンポーネントはSHFBに含まれています。

「Intellisenseコンポーネント」をSHFBプロジェクトに追加する必要があります。次に、構成されたSHFBプロジェクトに従ってXMLを生成します。

詳細情報:SHFBのIntellisenseコンポーネント

于 2011-06-01T19:24:53.653 に答える
4

eazfuscatorには、公開されていないドキュメントを削除できるツールがあります。ここで例を見ることができます

于 2011-06-01T04:13:06.383 に答える
3

私はこれについて少し考え、この特定の問題を解決する方法を変えることにしました。アセンブリ内で型/メンバーを見つける代わりに、XML ドキュメント表記を解析しようとします。メンバーが公開されていないかどうかをテストするために使用できる、公開 API 用の (XML ドキュメント表記の) 文字列セットを単純に作成することにしました。

それは本当に簡単です。にアセンブリを送信するXmlDocumentationStringSetと、パブリック API の文字列セットが作成され、パブリックではない要素が削除されます。

static void Main(string[] args)
{
    var el = XElement.Load("ConsoleApplication18.XML");

    // obviously, improve this if necessary (might not work like this if DLL isn't already loaded)
    // you can use file paths
    var assemblyName = el.Descendants("assembly").FirstOrDefault();
    var assembly = Assembly.ReflectionOnlyLoad(assemblyName.Value);

    var stringSet = new XmlDocumentationStringSet(assembly);

    foreach (var member in el.Descendants("member").ToList()) // .ToList enables removing while traversing
    {
        var attr = member.Attribute("name");
        if (attr == null)
        {
            continue;
        }
        if (!stringSet.Contains(attr.Value))
        {
            member.Remove();
        }
    }

    el.Save("ConsoleApplication18-public.XML");
}

XML ドキュメント名を作成するクラスは次のとおりです (少し大きいですが、とにかくソース全体をここに投稿すると思いました)。

using System;
using System.Collections.Generic;
using System.Linq;
using System.Reflection;
using System.Text;

namespace ConsoleApplication18
{
    public class XmlDocumentationStringSet : IEnumerable<string>
    {
        private HashSet<string> stringSet = new HashSet<string>(StringComparer.Ordinal);

        public XmlDocumentationStringSet(Assembly assembly)
        {
            AddRange(assembly.GetExportedTypes());
        }

        public bool Contains(string name)
        {
            return stringSet.Contains(name);
        }

        /// <summary>
        /// Heelloasdasdasd
        /// </summary>
        /// <param name="types"></param>
        public void AddRange(IEnumerable<Type> types)
        {
            foreach (var type in types)
            {
                Add(type);
            }
        }

        public void Add(Type type)
        {
            // Public API only
            if (!type.IsVisible)
            {
                return;
            }
            var members = type.GetMembers(BindingFlags.Instance | BindingFlags.Static | BindingFlags.NonPublic | BindingFlags.Public);
            foreach (var member in members)
            {
                Add(type, member);
            }
        }

        StringBuilder sb = new StringBuilder();

        private void Add(Type type, MemberInfo member)
        {
            Type nestedType = null;

            sb.Length = 0;

            switch (member.MemberType)
            {
                case MemberTypes.Constructor:
                    sb.Append("M:");
                    AppendConstructor(sb, (ConstructorInfo)member);
                    break;
                case MemberTypes.Event:
                    sb.Append("E:");
                    AppendEvent(sb, (EventInfo)member);
                    break;
                case MemberTypes.Field:
                    sb.Append("F:");
                    AppendField(sb, (FieldInfo)member);
                    break;
                case MemberTypes.Method:
                    sb.Append("M:");
                    AppendMethod(sb, (MethodInfo)member);
                    break;
                case MemberTypes.NestedType:
                    nestedType = (Type)member;
                    if (IsVisible(nestedType))
                    {
                        sb.Append("T:");
                        AppendNestedType(sb, (Type)member);
                    }
                    break;
                case MemberTypes.Property:
                    sb.Append("P:");
                    AppendProperty(sb, (PropertyInfo)member);
                    break;
            }

            if (sb.Length > 0)
            {
                stringSet.Add(sb.ToString());
            }

            if (nestedType != null)
            {
                Add(nestedType);
            }
        }

        private bool IsVisible(Type nestedType)
        {
            return nestedType.IsVisible;
        }

        private void AppendProperty(StringBuilder sb, PropertyInfo propertyInfo)
        {
            if (!IsVisible(propertyInfo))
            {
                sb.Length = 0;
                return;
            }
            AppendType(sb, propertyInfo.DeclaringType);
            sb.Append('.').Append(propertyInfo.Name);
        }

        private bool IsVisible(PropertyInfo propertyInfo)
        {
            var getter = propertyInfo.GetGetMethod();
            var setter = propertyInfo.GetSetMethod();
            return (getter != null && IsVisible(getter)) || (setter != null && IsVisible(setter));
        }

        private void AppendNestedType(StringBuilder sb, Type type)
        {
            AppendType(sb, type.DeclaringType);
        }

        private void AppendMethod(StringBuilder sb, MethodInfo methodInfo)
        {
            if (!IsVisible(methodInfo) || (methodInfo.IsHideBySig && methodInfo.IsSpecialName))
            {
                sb.Length = 0;
                return;
            }
            AppendType(sb, methodInfo.DeclaringType);
            sb.Append('.').Append(methodInfo.Name);
            AppendParameters(sb, methodInfo.GetParameters());
        }

        private bool IsVisible(MethodInfo methodInfo)
        {
            return methodInfo.IsFamily || methodInfo.IsPublic;
        }

        private void AppendParameters(StringBuilder sb, ParameterInfo[] parameterInfo)
        {
            if (parameterInfo.Length == 0)
            {
                return;
            }
            sb.Append('(');
            for (int i = 0; i < parameterInfo.Length; i++)
            {
                if (i > 0)
                {
                    sb.Append(',');
                }
                var p = parameterInfo[i];
                AppendType(sb, p.ParameterType);
            }
            sb.Append(')');
        }

        private void AppendField(StringBuilder sb, FieldInfo fieldInfo)
        {
            if (!IsVisible(fieldInfo))
            {
                sb.Length = 0;
                return;
            }
            AppendType(sb, fieldInfo.DeclaringType);
            sb.Append('.').Append(fieldInfo.Name);
        }

        private bool IsVisible(FieldInfo fieldInfo)
        {
            return fieldInfo.IsFamily || fieldInfo.IsPublic;
        }

        private void AppendEvent(StringBuilder sb, EventInfo eventInfo)
        {
            if (!IsVisible(eventInfo))
            {
                sb.Length = 0;
                return;
            }
            AppendType(sb, eventInfo.DeclaringType);
            sb.Append('.').Append(eventInfo.Name);
        }

        private bool IsVisible(EventInfo eventInfo)
        {
            return true; // hu?
        }

        private void AppendConstructor(StringBuilder sb, ConstructorInfo constructorInfo)
        {
            if (!IsVisible(constructorInfo))
            {
                sb.Length = 0;
                return;
            }
            AppendType(sb, constructorInfo.DeclaringType);
            sb.Append('.').Append("#ctor");
            AppendParameters(sb, constructorInfo.GetParameters());
        }

        private bool IsVisible(ConstructorInfo constructorInfo)
        {
            return constructorInfo.IsFamily || constructorInfo.IsPublic;
        }

        private void AppendType(StringBuilder sb, Type type)
        {
            if (type.DeclaringType != null)
            {
                AppendType(sb, type.DeclaringType);
                sb.Append('.');
            }
            else if (!string.IsNullOrEmpty(type.Namespace))
            {
                sb.Append(type.Namespace);
                sb.Append('.');
            }
            sb.Append(type.Name);
            if (type.IsGenericType && !type.IsGenericTypeDefinition)
            {
                // Remove "`1" suffix from type name
                while (char.IsDigit(sb[sb.Length - 1]))
                    sb.Length--;
                sb.Length--;
                {
                    var args = type.GetGenericArguments();
                    sb.Append('{');
                    for (int i = 0; i < args.Length; i++)
                    {
                        if (i > 0)
                        {
                            sb.Append(',');
                        }
                        AppendType(sb, args[i]);
                    }
                    sb.Append('}');
                }
            }
        }

        public IEnumerator<string> GetEnumerator()
        {
            return stringSet.GetEnumerator();
        }

        System.Collections.IEnumerator System.Collections.IEnumerable.GetEnumerator()
        {
            return GetEnumerator();
        }
    }
}

イベントの処理方法はまだわかりませんが、この例では常に表示されています。

于 2011-06-03T15:44:40.037 に答える
2

@ジョン・ライデグレン

私は同じ要件を持っており、あなたのコードの欠けているビットに対する答えを見つけました。Event には Add と Remove の 2 つのメソッドがあり、いずれかが公開されている場合、公開されていると見なされます。したがって、次のようになります。

private bool IsVisible(EventInfo eventInfo)
{
    return eventInfo.GetAddMethod(false) != null
        || eventInfo.GetRemoveMethod(false) != null;
}

一方が公開され、もう一方が公開されない理由は思いつきません。

于 2012-10-10T10:40:18.640 に答える
0

私は同じ問題に直面していました。SHFB は非常に遅く、別のドキュメント コード ベースがあるため、ドキュメントを生成する必要はありませんでした。

XMLStarletに加えて、内部クラス用の別の名前空間を使用することになりました。たとえば、すべての内部クラスはMyCompany.MyProduct.Internal. 次に、1 つの簡単なコマンドを使用できます。

xml ed -L -d "//member[contains(@name, 'MyCompany.MyProduct.Internal')]" MyProduct.xml

XML をクレンジングします。もちろん、これは防弾ではありません。パブリック クラスの内部メンバーは対象外であり、内部クラスを内部に配置することを覚えておくには、ある程度の規律が必要です。しかし、これは私にとって最もクリーンで邪魔にならない方法です。また、ビルド サーバーに簡単にチェックインできるスタンドアロンの EXE ファイルでもあります。

于 2011-07-04T07:45:17.010 に答える
0

ドキュメントの生成に使用しているツールは何ですか? 私は Sandcastle を使用しています。これにより、アクセシビリティによって含めるメンバーを選択するオプションが提供されます。

一般に、XML には必要となる可能性のあるすべての情報が含まれており、その中から必要なものを選択するのは処理ツール次第であると予想されます。

于 2009-03-08T22:41:56.093 に答える