Archive for the 'documentation' Category

Published by breki on 31 Mar 2008

Tip: How To Speed-Up Sandcastle

Simply remove (or rename) the Data/Reflection directory, so that Sandcastle cannot find the information about .NET Framework libraries. You will loose the ability to have MSDN help on .NET Framework classes links in your documentation, but I think this is not crucial for day-to-day builds, compared to the substantial increase in your build speed. And also, by deleting the contents of the Reflection folder you’ll gain some 200 MB of space on your disk.

Published by breki on 31 Jan 2008

Generating WSDL documentation as part of the NAnt build

WSDLs are not very readable, so I wanted to have some sort of developer-friendly documentation for web services as part of our CI build. I found a simple but effective solution: WSDL viewer (by Tomi Vanek), which is an XSLT transformation file that produces nice HTML documentation.

I had to create a custom NAnt task for XSLT transformations since <style> task failed when I tried to do transformations using the WSDL viewer XSLT (it was complaining about some XML elements not being declared):


    <script language="C#" prefix="Brejc.NAntTasks.">
        <code>
            <![CDATA[
   [TaskName("xslt")]
   public class XsltTask : Task
   {
       [TaskAttribute ("inputfile", Required = true)]
       public string InputFile
       {
           get { return inputFile; }
           set { inputFile = value; }
       }

       [TaskAttribute ("outputfile", Required = true)]
       public string OutputFile
       {
           get { return outputFile; }
           set { outputFile = value; }
       }

       [TaskAttribute ("xsltfile", Required = true)]
       public string XsltFile
       {
           get { return xsltFile; }
           set { xsltFile = value; }
       }

       protected override void ExecuteTask ()
       {
           XsltSettings xsltSettings = new XsltSettings (true, true);
           XmlDocument xsltDoc = new XmlDocument();
           xsltDoc.Load (xsltFile);

           XmlUrlResolver resolver = new XmlUrlResolver ();
           XslCompiledTransform transform = new XslCompiledTransform (true);
           transform.Load (xsltDoc, xsltSettings, resolver);

           using (Stream inputStream = File.Open (inputFile, FileMode.Open, FileAccess.Read))
           {
               XmlReader reader = XmlReader.Create (inputStream);
               using (XmlWriter writer = XmlWriter.Create (outputFile))
                   transform.Transform (reader, writer);
           }
       }

       private string inputFile;
       private string outputFile;
       private string xsltFile;
   }
             ]]>
        </code>
        <references>
            <include name="System.Xml.dll"></include>
        </references>
        <imports>
            <import namespace="System.IO"></import>
            <import namespace="System.Xml"></import>
            <import namespace="System.Xml.Xsl"></import>
        </imports>
    </script>

Now all you need is to use this task to create the documentation:


    <target name="docs.wsdl" description="generates wsdl based on the existing web services">
        <mkdir dir="doc\wsdl" unless="${directory::exists(‘doc\wsdl’)}">
        <xslt inputfile="SomeWebService.wsdl">
              outputfile="doc\wsdl\SomeWebService.html"
              xsltfile="lib\WsdlViewer\wsdl-viewer.xsl"/>
    </xslt>
</mkdir></target>

Published by breki on 29 Jan 2008

C# Source Code Search Engines For Internal Use

I work on a lot of different projects, both in the company I work for and in my spare time. A lot of code has been produced during that time and I constantly find myself searching for that “I remember I once wrote something like this” code. Google helps, but its search engine is not specialized for C# code and I sometimes have to do a lot of searching before finding a snippet that is perfect for my needs. Snippets in VisualStudio are helpful too, but I use them mostly for really repetitive code which merits taking time to write the snippet.

So I started to look for a search engine that would be able to go through my C# source code (and possibly source code repositories like SVN) and offer more developer-oriented search capabilities (like, for example, searching for all classes that implement a certain interface).

Desktop Search

The first thing popping up in my mind was using general desktop search engines (like Google Desktop or similar). In fact I used this approach few years ago when I played around with desktop search engines on my laptop. The problem with general search engines is the fact that they are too general: when you search for code using general search, all kinds of unrelated results pop up. And besides, installing Google Desktop just to search for my source code is a bit of an overkill for me.

Specialized Search Engines

My first stop was Koders Pro. This is a professional solution provided by Koders, an Internet source code search engine which indexes open source projects. I tried Koders Pro beta version just before it went to market and I liked it. It offers most of the features I was looking for. I liked the fact that it knows how to connect to various code versioning systems like SVN. What I didn’t like is the fact that you have to sign up online on Koders website in order to access your company’s internal search site. I like to have those things separated: what I do on my (or my company’s) private network is my own business, thank you (looks like someone else agrees with me).

Open Source Solutions

But since I wanted to have the search capability available not only on projects I work on professionally, but also for my own personal stuff, I was looking for a free (or not too expensive) preferably open source solution. So I started investigating (more or less googling).

I found a very interesting article called Using Lucene to Search Java Source Code. As the name says, it describes how to implement a search engine for Java source code using Lucene, an open source search engine library. The article describes the approach in quite a detail, I won’t go into it since this is not the purpose of this post. But anyway, it was a good point from which to start searching in a more focused way. I also found a related article, Source Code Search with Syntax-Based Heuristics, which builds upon the first article’s idea, but is more ambitious.

CS2 Project

Finally, I stumbled upon CS2 Project. This is an open source academic project created by Simone Busoli. It too uses Lucene (Lucene.Net actually) as a search engine. What I like about CS2 is its extreme simplicity. You just download the zipped binaries package, extract it somewhere on your disk, create an IIS web application for it and that’s it! No MSI installations, no extra Windows services.

When you browse to the CS2 application page, you get two text boxes: the first one is used for entering search keywords, the second one for registering paths on your disk which contain source code and should be indexed.

CS2 even offers some basic query parameters, like searching for method names, comments etc. It also supports search wildcards.

Okey, it’s not feature rich as Koders, but on the other hand the basic functionality it offers is a step in the right direction.

OpenGrok

While I was writing this post I ran into OpenGrok, an open source search engine written in Java. It supports multiple languages search, but I couldn’t find any information on whether it supports indexing of C# sources.

I will post about any new findings in the future.