When you create the big software solution, you usually need the technical documentation. Since some time there exists the automated documentation builders like NDoc. As I had some previous experiences in VS.Net 2003 (.Net 1.1), I was quite sure it will be nice and quick task to do the thing. How big my surprise was, that new technologies does not always make people live easier! :)
Basic NDoc is no longer supported for VS.Net 2005! The last NDoc version 1.3.1 does not work for .Net 2.0. There is some way to change the configuration file, so .Net 2.0 solutions are supported, but this is rather workaround than a complex solution.
I decide to look for some other new “mainstream” solution and I have installed the Sandcastle, especially that there is quite a number of fellows talking about the solution – among others Tomasz Kopacz, who is local, polish tech guru. The main page to start exploring the whole topic is not so popular on Google search. Sandcastle has surprised me because it does not provide you the GUI within the main package and you must download some additional tool for it like the Sandcastle Help File Builder. Unfortunately there is the other back fire and you must have generated xml file with comments (XmlCommentsPath), which was not necessary in old good NDoc! There is some nice project, explaining the basics, however it supposed to be some simple task!
As expected, I am not the only one who has this type of problem and there is number of places, where this discussion repeats – Joel on Software is one of them. I started to look for some other solutions, but most of them like DocumentX or Doc-O-Matic are not for free. Doxygen looks quite odd. And then the whole loop closed…
NDoc 2.0 Alpha, published by Kyno Sarges, who truly did the tremendous job seems to be so far the best option for old NDoc fellows. It is quite sad that NDoc home page is DEAD and you must to look for the remedy in such a places, but it works. It beats Sandcastle definitely and furthermore it provides you the comments’ xml file as well, but the difference is IT IS OPTIONAL! Unfortunately it is no longer possible to consume the whole solution file and have the documentation ready in a minute, but… at least you can do something quickly, without the necessity of writing custom files per project.
There is a good document, which described most of common problems with NDoc2 Alpha. The major problem is though that NDoc2 is no longer supported! Dead body again :) There is also the other drawback - unlike in NDoc 1.3.1 you must generate the xml comment file for each project separately (!) and add it to compilation in order to get summary and parameters tags consumed. How to make a trick is described in details in the article and the other one. The positive thing is that you can easily switch on one the parameters so the final chm document shows you in read which summary or parameter is missing the content of the comment and in such a way you can easily find the places in code to fill in.
So this is how the whole story finishes – there is one thing, which I sure of. Creating technical documentation for software solutions takes now much more time and effort than it did before! :)
Basic NDoc is no longer supported for VS.Net 2005! The last NDoc version 1.3.1 does not work for .Net 2.0. There is some way to change the configuration file, so .Net 2.0 solutions are supported, but this is rather workaround than a complex solution.
I decide to look for some other new “mainstream” solution and I have installed the Sandcastle, especially that there is quite a number of fellows talking about the solution – among others Tomasz Kopacz, who is local, polish tech guru. The main page to start exploring the whole topic is not so popular on Google search. Sandcastle has surprised me because it does not provide you the GUI within the main package and you must download some additional tool for it like the Sandcastle Help File Builder. Unfortunately there is the other back fire and you must have generated xml file with comments (XmlCommentsPath), which was not necessary in old good NDoc! There is some nice project, explaining the basics, however it supposed to be some simple task!
As expected, I am not the only one who has this type of problem and there is number of places, where this discussion repeats – Joel on Software is one of them. I started to look for some other solutions, but most of them like DocumentX or Doc-O-Matic are not for free. Doxygen looks quite odd. And then the whole loop closed…
NDoc 2.0 Alpha, published by Kyno Sarges, who truly did the tremendous job seems to be so far the best option for old NDoc fellows. It is quite sad that NDoc home page is DEAD and you must to look for the remedy in such a places, but it works. It beats Sandcastle definitely and furthermore it provides you the comments’ xml file as well, but the difference is IT IS OPTIONAL! Unfortunately it is no longer possible to consume the whole solution file and have the documentation ready in a minute, but… at least you can do something quickly, without the necessity of writing custom files per project.
There is a good document, which described most of common problems with NDoc2 Alpha. The major problem is though that NDoc2 is no longer supported! Dead body again :) There is also the other drawback - unlike in NDoc 1.3.1 you must generate the xml comment file for each project separately (!) and add it to compilation in order to get summary and parameters tags consumed. How to make a trick is described in details in the article and the other one. The positive thing is that you can easily switch on one the parameters so the final chm document shows you in read which summary or parameter is missing the content of the comment and in such a way you can easily find the places in code to fill in.
So this is how the whole story finishes – there is one thing, which I sure of. Creating technical documentation for software solutions takes now much more time and effort than it did before! :)
ps.
My programmers finally have chosen the Sandcastle as it is the only one supported by the Microsoft and they have convinced me. I am just after the second review of the generated technical documentation and I love the options showing on red what is missing ;)
Brak komentarzy:
Prześlij komentarz