Showing posts with label documentation. Show all posts
Showing posts with label documentation. Show all posts

2008-12-11

First steps to success!

I was thinking, how come I have no completed hobby projects? I couldn't find a reason, so I concluded that perhaps I'm too stupid to complete anything. Then I open Visual Studio again and started thinking what other features I might need in my utility library... Then it struck me! I haven't completed anything, because none of my hobby projects had requirements or design documents (which, IMHO, is the same thing)! So, I decided, that I will never write a single line of code, without having requirements or design documentation written.

I was very happy and excited, but then I've come to another problem. What document format to use for the documentation? Being an inch smarter than I was five minutes ago, I decided to gather the requirements for the document format, and then try to find one that matches as many as possible of those requirements. So, I fired up my good friend Notepad++ and started typing...

Here are the most important requirements:

  • Version control system friendly or in other words - it must be a text based format, I must be able to diff two versions of the document and so on.
  • If the format isn't easily editable by hand - it must have at least one free editor. Note that WYSIWYG editor is not required.
  • IT must be easy to separate content from presentation.
  • The format must support embeddable elements (and they must be easily editable/replaceable):
    • Tables;
    • Images;
    • Diagrams (this one is optional, because I can embed images).
I immediately knew, that what I'm describing is HTML (or XHTML). After some googling, I also found DocBook, and some more XML-based formats. I liked none of them! XML is a horrible language to edit by hand (you have to remember to close the tags, you have to replace some characters with their codes etc.)

Then, while reading something about DocBook, I saw LaTeX being mentioned. I looked at it... And I couldn't believe I wasn't using it already! It's my kind of way to create documents. I mean, how often can you tell someone, that you're compiling your documents? :)

And besides, LaTeX meets all of my requirements. Text based, free editors (any text editor, or something more WYSIWYG-ish like LyX or TeXnic can be used), content separation from the presentation is probably the main philosofy of all TeX formats, through some external packages LaTeX let's you embed almost anything.

So now, I have MiKTeX, and I'm experimenting with document classes and packages. I will probably create my own classes, because I want to have the common look and feel.

If you're a programmer like me - have a look at LaTeX! It's brilliant!

2007-09-13

The Tools: Documentation generator

The tools I've discussed so far have obvious use for every developer. This one, however is something different. Most programmers do not use any source code documentation generators. Heck, I started using one only a few weeks ago! I like it so far.

So, what tools should you consider, when you're developing applications with C++? Well, the first one I thought of was doxygen. It is probably the most popular tool in the world. Most of the open source libraries use it. You want my own opinion? Well, it sure can parse C++ code, though it generates some stupid warnings occasionally. The actual documentation comments are ugly. I mean, really, writing commands like \ref or $ref is ugly. If you're reading The Code, and not The Documentation - the comments are very cryptic and hard to read. Another thing I should mention is that I really don't like that doxygen doesn't let you customize the look of generated documentation. I would really love if it would let me fully customize the generated output (by supplying my own templates for class, function, member, template class and so on).

Another tool I've found was Natural Docs. Now, the first thing I want to say is that the documentation comments are great! It doesn't have any commands or tags. When you look at the source code - it just look like normal comments. However, the tool isn't perfect either. Its' support for C++ language is far from perfect. On the web site, it says that the update in this area is planned, though. So, when they implement full support for C++ language - this tool will become the best tool. But right now it's barely usable. Also, just as doxygen, Natural Docs doesn't let you customize the generated output. Oh, and the supported output formats are fewer.

There were some other tools I've looked at. Some of them look nice, some of them are awful, but none of them deserve a separate paragraph in this blog-post. Anyway, here's is the list of tools worth mentioning:

There aren't that many tools that generate documentation from source code...

So, what is my final word? I choose Doxygen. I will be keeping an eye on Natural Docs, but for now, I choose Doxygen.