|
NDoc ile Proje Dökümantasyonu |
|
Gönderiliyor lütfen bekleyin... |
|
|
NDoc, DotNet assemblyleri ve C# derleyicisi tarafından üretilen XML dökümantasyonu kullanarak DotNet sınıf kütüphaneleri dökümantasyonu üreten açık kaynak kodlu bir dökümantasyon aracıdır. Kullanımı ve ayarları oldukça kolaydır. Değişik dökümantasyon şablonları ve formatları sunar.
NDocu incelemeye başlamadan önce .NET araçları ve frameworkleri serimizin önceki bölümlerine ulaşmak için :
NAnt ile Build otomasyonu
NUnit ile birim test
VS.NET ve C# Derleyicisi Dökümantasyon Özellikleri
NDocun bir assembly için dökümantasyon oluşturabilmesi için, C# derleyicisi tarafından assembly için XML dökümantasyon dosyası oluşturulması gerekmektedir. Bu dosyayı oluşturmak için Visual Studio.NETte Project/Project Propertiesden aşağıdaki gibi dosya ismi belirliyoruz.
Resim 1. Proje özelliklerinden Xml dökümantasyonu oluşturulmasını aktif hale getiriyoruz.
Bu dosyanın anlamlı bir dökümantasyon dosyası olabilmesi için projemizdeki namespaceler, sınıflar, metodlar, özellikler, ... vs. C# derleyicisinin parse edeceği tagler ile dökümante edilmiş olmalıdır. C# derleyicisi üç slash (///) karakterini takip eden özelleştirilmiş commentlerden Xml dökümantasyon dosyasını oluşturur.
Doğrulanan tagler (kodun dökümantasyon ile uyumlu olup olmadığı C#derleyicisi tarafından doğrulanır ve gerekli uyarılar verilir) ve doğrulanmayan tagler olmak üzere ikiye ayrılan dökümantasyon amaçlı tagleri incelemeye çalışalım :
Doğrulanan Tagler
- <exception> : Yazılan metodun belli bir durumda belirtilen hatayı fırkatacağını belirtir.
- <include> : Başka bir dökümantasyon dosyasına referans verilir.
- <param> : Metod parametreleri için kullanılır. Intellisense ve ObjectBrowser tarafından kullanılır.
- <paramref> : Metod parametreleri için kullanılır. Dökümantasyon amaçlıdır.
- <permission> : Yazdığımız metodun erişilebilirliğini belirtmek için kullanılır.
- <see> : Dökümantasyonumuz içerisinde link vermemizi sağlar.
- <seealso> : Dökümantasyonumuz içerisinde konu ile ilgili diğer konulara link vermemizi sağlar.
Doğrulanmayan Tagler
- <example> : Örnek kod vermemize olanak sağlar.
- <c> : Dökümantasyon içerisinde kullandığımız kodları belirtmek için kullanılır.
- <code> : Çok satırlı kod örneği verildiğini belirtir.
- <list> : Maddeler halinde liste oluşturmayı sağlar.
- <para> : Dökümantasyonumuzu paragraflara bölmemize olanak sağlar.
- <remarks> : Tip veya metod hakkında ek bilgi tanımlamayı sağlar.
- <returns> : Metodlar için dönüş değerini belirtmeye yarar.
- <summary> : Tip veya metod hakkında kısa açıklama yapmaya olanak sağlar.
- <value> : Özellikler için değerin tanımlanmasını sağlar.
/// <summary>
/// Parametre olarak geçilen nesneyi
///(<c>silinecekNesne</c>), listede var ise çıkartır.
/// </summary>
/// <param name="silinecekNesne">Listeden silinecek sınıf.</param>
/// <returns>Listeden çıkarma işlemi yapılırsa true,
/// yapılmazsa false döndürür.</returns>
/// <exception cref="System.ArgumentNullException">
/// Eğer <paramref name="silinecekNesne" /> <c> null</c> ise.
/// </exception>
/// <example>
/// <code>
/// DenemeSinifi deneme = new DenemeSinifi();<br/>
/// liste.ListeyeEkle(deneme);<br/>
/// bool nesne1SilindiMi = liste.Remove(deneme);<br/>
/// // nesne1SilindiMi -> true<br/>
/// bool nesne2SilindiMi = liste.Remove(new DenemeSinifi());<br/>
/// // nesne2SilindiMi -> false
/// </code>
/// </example>
public bool ListedenCikar(object silinecekNesne)
{
if (silinecekNesne == null)
{
throw new ArgumentNullException();
}
if (this._liste.Contains(silinecekNesne))
{
this._liste.Remove(silinecekNesne);
return true;
}
else
{
return false;
}
}
|
NDoc ile dökümantasyonun oluşturulması
Yukarıdaki örnek kodda olduğu gibi kodumuza gerekli açıklamaları ekledikten sonra proje özelliklerinden, makalemin başında bahsettiğim gibi, Xml dökümantasyon dosyasının yeri belirlenmelidir. Proje derlendikten sonra belirttiğimiz dizinde Xml dökümantasyon dosyamızın oluştuğunu göreceksiniz.
Şimdi assemblymizi ve Xml dökümantasyon dosyamızı kullanarak proje dökümantasyonunu oluşturalım :
Resim 2. NDoc aracı arayüzü. Assemblymizi ve XML dökümantasyonumuzu NDoc projesine dahil ediyoruz.
Yukarıdaki şekildeki gibi ister eklemek istediğimiz assemblyleri tek tek NDoc dökümantasyon projesine dahil edebiliriz, istersek de VS.NET solution dosyasından (*.sln) NDoc projesi oluşturabiliriz. Daha sonra dökümantasyon stilini ve gerekli ayar ve parametreleri girdikten sonra NDoc arayüzünü kullanaran dökümantasyon dosyamızı oluştururuz.
Resim 3. NDoc aracı ile oluşturulmuş MSDN stilinde örnek dökümantasyon dosyası.
NOT : NDoc, chm uzantılı derlenmiş Html dosyası (Compiled HTML) oluşturmak için HTML Help Workshopu kullanır. VS.NET kurulu bir bilgisayarda bu uygulama zaten kuruludur. Emin olmak için C:\Program Files\HTML Help Workshop dizinini kontrol edebilirsiniz. Eğer Bu uygulama bilgisayarınızda yoksa buradan indirebilirsiniz.
NDoc NAnt Entegrasyonu
.NET araçları ve Frameworklari serimin ilk makalesinde incelediğim NAnt build otomasyon aracı ile proje dökümantasyonunu build otomasyonumuza eklemek için <ndoc> görevini (task) kullanabiliriz.
<?xml version="1.0"?>
<project name="NAnt NDoc Dokumantasyon Projesi" default="documentation">
<target name="documentation">
<ndoc>
<assemblies>
<include name="E:\Works\C#\NDocDemo\bin\Debug\NDocDemo.dll" />
</assemblies>
<summaries>
<include name="E:\Works\C#\NDocDemo\bin\Debug\NDocDemo.xml" />
</summaries>
<documenters>
<documenter name="MSDN">
<property name="OutputDirectory" value="E:\Works\C#\NDocDemo\doc" />
<property name="HtmlHelpName" value="NAntGeneratedHelpFile" />
<property name="HtmlHelpCompilerFilename" value="hhc.exe" />
<property name="IncludeFavorites" value="False" />
<property name="Title"
value="NAnt tarafindan uretilmis NDoc Demo Dokumantasyonu" />
<property name="SplitTOCs" value="False" />
<property name="ShowMissingSummaries" value="True" />
<property name="ShowMissingRemarks" value="True" />
<property name="ShowMissingParams" value="True" />
<property name="ShowMissingReturns" value="True" />
<property name="ShowMissingValues" value="True" />
<property name="DocumentInternals" value="False" />
<property name="DocumentProtected" value="True" />
<property name="DocumentPrivates" value="False" />
<property name="DocumentEmptyNamespaces" value="False" />
<property name="IncludeAssemblyVersion" value="False" />
<property name="CopyrightText" value="C#nedir?com" />
<property name="CopyrightHref" value="http://www.csharpnedir.com/" />
</documenter>
</documenters>
</ndoc>
</target>
</project>
|
Sonuç
Uygulama geliştiricilerin en çok sıkıldıkları işlerden biri dökümantasyon yapmak, ve güncellemelerde de bu dökümantasyonu güncel tutmaktır. En sancısız dökümantasyon proje geliştirilirken taze taze yapılan dökümantasyondur. VS.NETin sunduğu sihirli üç slash sayesinde dökümantasyonları yazman çok daha kolay. NDocu kullanarak proje dökümantasyonlarımızı standart bir şablonda oluşturmak çok çok kolay bir iş olduğunu bu makalemde göstermeye çalıştım.
NDocun sağladığı bir diğer avantaj ise NAnt entegrasyonudur. Böylece her derlemede proje dökümantasyonunu güncel tutmuş oluyoruz. .NET araçları ve Frameworkleri serimin bir sonraki bölümünde görüşmek üzere..
Makalede anlatılan örnekleri indirmek için tıklayın.
Kaynaklar ve Linkler
Makale:
NDoc ile Proje Dökümantasyonu C#, Visual C# ve .NET Mustafa Erhan Ersoy
|
|
|
-
-
Eklenen Son 10
-
Bu Konuda Geçmiş 10
Bu Konuda Yazılmış Yazılmış 10 Makale Yükleniyor
Son Eklenen 10 Makale Yükleniyor
Bu Konuda Yazılmış Geçmiş Makaleler Yükleniyor
|
|