C#nedir?com
 
YAZAR HAKKINDA
Mustafa Erhan Ersoy
Mustafa Erhan Ersoy
http://www.csharpnedir.com/
İletişme geçmek için tıklayın.
14 Makalesi yayınlanmakta.
Yazar hakkında detaylı bilgi için tıklayın.
Yayınlanan diğer makaleleri için tıklayın.
İlgili etiketler: assembly assemblyleri derleyicisi dosyasi dotnet frameworkleri gerekli incelemeye kullanarak kullanilir. metodun olanak olusturmak parametreleri tagler C# / VC#/.NET Mustafa Erhan Ersoy
 
YAZI HAKKINDA
Türü : Makale
Serbest Köşede C#nedir?com üyelerinin hazırladıkları yazılar yayınlanır. Bu yazılar editör incelemesine girmeden yayınlanır.
Seviyesi : Orta
Kategori : C# / VC#/.NET
Yayınlanma Tarihi : 9.11.2005
Okunma Sayısı : 25247
Yorum Sayısı : 0     yorum yaz
Site İçi AramaSİTE İÇİ ARAMA
Üye Girişini AçÜye GİRİŞİ
Üye girişi için tıklayın.
Kullanıcı Adı
Şifre
 
Beni her zaman hatırla
Bir hafta boyunca kullanıcı bilgilerinizi kullanıcı çıkışı yapana kadar hatırlar. (Paylaşılan bilgisayarlarda önerilmez.)
 
Şifremi / Kullanıcı Adımı unuttum.
 
.net TV RSS Serbest KÖŞE (?)
Serbest Köşede C#nedir?com üyelerinin hazırladıkları yazılar yayınlanır. Bu yazılar editör incelemesine girmeden yayınlanır.
emre TAŞ
XML - Deniz Kılınç
emre TAŞ
yazının devamı >
emre TAŞ
Decompiling and Reverse Engineering .Net Radyo
emre TAŞ
yazının devamı >
emre TAŞ
Masaüstü mü ? İnternet Mi? .Net Radyo
emre TAŞ
yazının devamı >
emre TAŞ
.Net Kavramları - .Net Radyo
emre TAŞ
yazının devamı >
emre TAŞ
Yeni Başlayanlar için - .Net Radyo
emre TAŞ
yazının devamı >
Makale Gönder Bende Yazmak İstiyorum
.net TV RSSBlogroll
Turhal Temizer
Conda install environment.yml Package 12.4.2021
Turhal Temizer
Mac OS/X Removing CUDA 12.4.2021
Burak Selim Şenyurt
Tie Fighter Değil, Project Tye! 12.4.2021
Burak Selim Şenyurt
Stackoverflow Sevgi Anketinde Yıllardır Bir Numara Çıkan Programlama Dili Rust Kimdir? 12.4.2021
  Diğer Herşey
Sponsorlar
BT Akademi
Medya Portakal
Video Hosting Sponsoru
Csharpnedir.com bir Ineta üyesidir
Uzman Abi
Her Yönüyle C# - Sefer Algan
NDoc ile Proje Dökümantasyonu
 
Kapat
Sayfayı Yazdır Sık Kullanılanlara Ekle Arkadaşıma Gönder MySpace Del.Ico.Us Digg Facebook Google Mixx Reddit StumbleUpon
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.

NDoc’u 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 NDoc’un 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.NET’te Project/Project Properties’den 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ü. Assembly’mizi 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 Workshop’u 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.NET’in sunduğu sihirli üç slash sayesinde dökümantasyonları yazman çok daha kolay. NDoc’u 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. NDoc’un 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
  • Yazılan Yorumlar
  • Yorum Yaz
Bu konu hakkında yayınlanan yorum bulunmamaktadır.
"Yorum Yaz" tabını kullanarak sizde yorumlarınızı yazabilirsiniz.
Yorum yazabilmek için üye girişi yapmalısınız. Üye girişi için tıklayın.
Üye değilseniz Üyel Ol linkine tıklayarak üyeliğinizi hemen başlatabilirisniz.
 
  • Bu Konuda Son 10
  • 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