C # dilinde arayüz ve uygulama yorumlarını senkronize etmenin yolları [kapalı]

Bir arayüz ve uygulaması arasında yorumları senkronize etmenin otomatik yolları var mı? Şu anda her ikisini de belgeliyorum ve manuel olarak senkronize halde tutmak istemiyorum.

GÜNCELLEME:

Bu kodu düşünün:

interface IFoo{
    /// <summary>
    /// Commenting DoThis method
    /// </summary>
    void DoThis();
}
class Foo : IFoo {
    public void DoThis();
}

Böyle bir sınıf oluşturduğumda:

IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense

Burada yorumlar gösterilmiyor:

Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense

<inheritDoc/>Etiket mükemmel Kum Castle belgeler üretecek, ancak intellisense tooltips çalışmaz.

Lütfen fikirlerinizi paylaşın.

Teşekkürler.

Bunu Microsoft Sandcastle (veya NDoc) inheritdocetiketini kullanarak oldukça kolay bir şekilde yapabilirsiniz . Teknik özellik tarafından resmi olarak desteklenmiyor, ancak özel etiketler tamamen kabul edilebilir ve gerçekten Microsoft bunu (ve bir veya iki diğer etiketi) Sandcastle'ı oluştururken NDoc'tan kopyalamayı seçti.

/// <inheritdoc/>
/// <remarks>
/// You can still specify all the normal XML tags here, and they will
/// overwrite inherited ones accordingly.
/// </remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}

İşte Sandcastle Yardım Dosyası Oluşturucu GUI'sinin kullanımını tam olarak açıklayan yardım sayfası.

(Elbette, sorunuzun da belirttiği gibi, bu özellikle "senkronizasyon" değildir, ancak yine de tam olarak aradığınız şey gibi görünecektir.)

Bir not olarak, bu bana tamamen adil bir fikir gibi geliyor, ancak bazı insanların türetilmiş ve uygulanan sınıflarda yorumları her zaman yeniden değerlendirmeniz gerektiğini düşündüğünü gözlemledim. (Aslında bunu kütüphanelerimden birini belgelendirirken kendim yaptım ve herhangi bir sorun görmedim.) Yorumların farklı olması için neredeyse her zaman hiçbir neden yoktur, öyleyse neden sadece miras alıp kolay yoldan yapmayasınız?

Düzenleme: Güncellemenizle ilgili olarak, Sandcastle sizin için bununla da ilgilenebilir. Sandcastle, girdi için kullandığı gerçek XML dosyasının değiştirilmiş bir sürümünü çıkarabilir; bu , bu değiştirilmiş sürümü doğrudan Visual Studio tarafından oluşturulan yerine kitaplık DLL'nizle birlikte dağıtabileceğiniz anlamına gelir, bu da açıklamalara intellisense ve dokümantasyon dosyası (CHM, ne olursa olsun).

Henüz kullanmıyorsanız, GhostDoc adlı ücretsiz bir Visual Studio eklentisini şiddetle tavsiye ederim . Dokümantasyon sürecini kolaylaştırır. Göz at my comment biraz ilgili soru üzerine.

GhostDoc senkronizasyonu otomatik olarak yapmasa da, aşağıdaki senaryoda size yardımcı olabilir:

Belgelenmiş bir arayüz yönteminiz var. Bu arayüzü bir sınıfa uygulayın, GhostDoc kısayol tuşuna basın Ctrl-Shift-Dve arayüzdeki XML yorumu uygulanan yönteme eklenecektir.

Git Seçenekler -> Klavye ayarları ve bir anahtar atamak GhostDoc.AddIn.RebuildDocumentation(kullandım Ctrl-Shift-Alt-D).

Şimdi, arayüzdeki XML açıklamasını değiştirirseniz, uygulanan yöntemde bu kısayol tuşuna basmanız yeterlidir ve dokümantasyon güncellenecektir. Ne yazık ki, bunun tersi geçerli değildir.

Genellikle şöyle yorumlar yazarım:

/// <summary>
/// Implements <see cref="IMyInterface.Foo(string, int)"/>
/// </summary>
/// <returns></returns>

Yöntemler yalnızca arayüz tarafından kullanılır, bu nedenle bu yorum kodlama sırasında araç ipuçlarında bile gösterilmez.

Düzenle:

Eğer doğrudan ve sınıf çağırdığınızda docs görmek istiyorsanız değil arayüzü kullanarak, iki kez bunu yazmak veya GhostDoc gibi bir araç kullanmak gerekir.

GhostDoc'u deneyin ! Benim için çalışıyor :-)

Düzenleme: Artık Sandcastle'ın desteğinden haberdar <inheritdoc/>olduğuma göre, Noldorin'in gönderisini destekliyorum. Bu çok daha iyi bir çözüm. Yine de GhostDoc'u genel olarak tavsiye ediyorum.

Daha iyi bir cevabım var: FiXml . , Yazarlarından biriyim

Klonlamak kesinlikle işe yarar bir yaklaşımdır, ancak önemli dezavantajları vardır, örneğin:

• Orijinal yorum değiştirildiğinde (geliştirme sırasında sıklıkla olur), klonu değişmez.
• Çok miktarda kopya üretiyorsunuz. Herhangi bir kaynak kodu analiz aracı kullanıyorsanız (örn. Takım Şehrinde Yinelenen Bulucu), esas olarak yorumlarınızı bulacaktır.

Bahsedildiği gibi Sandcastle'da<inheritdoc> etiket var , ancak FiXml'ye kıyasla birkaç dezavantajı var:

• Sandcastle derlenmiş HTML yardım dosyaları üretir - normalde .xmlayıklanmış XML yorumlarını içeren dosyaları değiştirmez (sonunda bu, derleme sırasında "anında" yapılamaz).
• Sandcastle'ın uygulaması daha az güçlü. Örneğin, hayır <see ... copy="true" />.

Daha fazla ayrıntı için Sandcastle'ın <inheritdoc>açıklamasına bakın.

FiXml'nin kısa açıklaması: C # \ Visual Basic .Net tarafından üretilen XML belgelerinin son işlemcisidir. MSBuild görevi olarak uygulanır, bu nedenle herhangi bir projeye entegre etmek oldukça kolaydır. Aşağıdaki dillerde XML belgeleri yazmayla ilgili birkaç can sıkıcı durumu ele alır:

• Belgeleri temel sınıftan veya arabirimden devralma desteği yoktur. Yani, geçersiz kılınan herhangi bir üye için bir belge sıfırdan yazılmalıdır, ancak normalde en azından bir kısmının devralınması oldukça arzu edilir.
• "Bu tür tekildir - <see cref="Instance" />tek örneğini almak için onun özelliğini kullanın" veya hatta " <CurrentType>Sınıfın yeni bir örneğini başlatır " gibi yaygın olarak kullanılan belge şablonlarının eklenmesine destek yoktur .

Bahsedilen sorunları çözmek için aşağıdaki ek XML etiketleri sağlanmıştır:

• <inheritdoc />, <inherited /> etiketleri
• <see cref="..." copy="..." /><see/>etiketindeki özellik .

İşte web sayfası ve indirme sayfası .

/// <inheritDoc/>

Burayı oku

Bunu kullan

<İnheritdoc /> etiketi için destek eklemek üzere XML dokümantasyon dosyalarını sonradan işlemek için bir kitaplık oluşturdum.

Kaynak kodda Intellisense ile yardımcı olmamakla birlikte, değiştirilmiş XML belge dosyalarının bir NuGet paketine dahil edilmesine izin verir ve bu nedenle başvurulan NuGet paketlerinde Intellisense ile çalışır.

Daha fazla bilgi için www.inheritdoc.io (ücretsiz sürümü mevcuttur).

Bunu yapma. Şöyle düşünün - her iki yorumun da her zaman aynı olması gerekiyorsa, o zaman bunlardan biri gerekli değildir. Yorum için bir neden olmalı (her işlevi ve değişkeni yorumlamak için bir tür tuhaf zorunluluğun yanı sıra), bu nedenle bu benzersiz nedenin ne olduğunu bulmanız ve bunu belgelemeniz gerekir.

ReSharper ile kopyalayabilirsiniz, ancak her zaman senkronize olduğunu düşünmüyorum.