January 6, 2009 at 02:07Automatic code documentation generator
I would like to introduce some code documentation generator. Of course, I would just like to take one of them and turn it on to make it work, but we have several problems so that you can leave your brain alone and not torment it with the integration of this whole thing.
The first and main problem- The current project is a web application. It uses two languages. JavaScript for the client side and PHP for the server side. The documentation is necessary for both the server and client side. By and large, nothing but kosher prevents you from using two different documentation generators. But I want it so that both parts of the project are handled the same way. I do not want to have a different appearance of documentation for different parts of one project. Plus, they will probably have different syntax requirements, which is also bad.
The second problem is that generators cannot parse JavaScript code. I almost chose Doxygen , but until I teach it my street JavaScript magic, I can’t use it corny. From the alternatives was found such a animal asJsDocToolkit . But he only earned almost. Although this is already an indicator - I haven’t set it up yet and there are few good comments in the code.
The third problem is that in the server part OOP is practically not used. But in any case, plans have been hanging for a long time to refactor the server side using OOP. Maybe even in python. So over time, this problem will disappear the same way. Moreover, the modular structure is there now. Problems in refactoring should not arise.
In summary. Spinning around their various representatives, I settled on Doxygen. According to the promises, it can be configured to work with languages that it does not support. Plus, in itself, it looks more powerful than other developments, which gives rise to hope for its flexibility.
Unfortunately, power and flexibility mean only one thing - for sure Doxygen is very difficult to master. And I still have to explain why all this is necessary and why it cannot be done in a simpler way. Trying to find some Russified site about Doxygen, I could not find anything like it. Maybe someone can tell me something adequate? Or will I need to translate English documentation in order to implement and use this solution? I’ll report
on the results of the implementation :)
The first and main problem- The current project is a web application. It uses two languages. JavaScript for the client side and PHP for the server side. The documentation is necessary for both the server and client side. By and large, nothing but kosher prevents you from using two different documentation generators. But I want it so that both parts of the project are handled the same way. I do not want to have a different appearance of documentation for different parts of one project. Plus, they will probably have different syntax requirements, which is also bad.
The second problem is that generators cannot parse JavaScript code. I almost chose Doxygen , but until I teach it my street JavaScript magic, I can’t use it corny. From the alternatives was found such a animal asJsDocToolkit . But he only earned almost. Although this is already an indicator - I haven’t set it up yet and there are few good comments in the code.
The third problem is that in the server part OOP is practically not used. But in any case, plans have been hanging for a long time to refactor the server side using OOP. Maybe even in python. So over time, this problem will disappear the same way. Moreover, the modular structure is there now. Problems in refactoring should not arise.
In summary. Spinning around their various representatives, I settled on Doxygen. According to the promises, it can be configured to work with languages that it does not support. Plus, in itself, it looks more powerful than other developments, which gives rise to hope for its flexibility.
Unfortunately, power and flexibility mean only one thing - for sure Doxygen is very difficult to master. And I still have to explain why all this is necessary and why it cannot be done in a simpler way. Trying to find some Russified site about Doxygen, I could not find anything like it. Maybe someone can tell me something adequate? Or will I need to translate English documentation in order to implement and use this solution? I’ll report
on the results of the implementation :)