Automatic code documentation generator
I want to introduce a generator of documentation code. 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 and PHP for the server. It is necessary that the documentation was made for both server and client parts. By and large, nothing but kosher does not prevent the use of two different documentation generators. But I want to, so that both parts of the project were treated the same. I do not want to have a different appearance of the documentation for different parts of the same project. Plus, they certainly will have different syntax requirements, which is also not good.
The second problem is that the generators cannot parse the JavaScript code. I have almost chosen Doxygen , but as long as I do not teach my street javascript magic, I simply cannot use it. Of the alternatives was found such an animal, as JsDocToolkit . 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 the OOP practically does not use the OOP. But in any case, plans for refactoring the server side using OOP have been hanging for a long time. Perhaps even on python. So over time, this problem will disappear as well. Especially since the modular structure is there now. Problems in refactoring should arise.
')
Summarizing. Having rotated on their various representatives, I stopped on Doxygen. If you believe promises, you can configure it to work with languages that it does not support. Plus, by itself, it looks more powerful than other developments, which gives rise to hope for its flexibility.
Unfortunately, power and flexibility mean only one thing - surely Doxygen is very difficult to master. And I also need to explain why this is all necessary and why it cannot be done in a simpler way. Having tried to find some Russified site about Doxygen, I could not find anything like that. Maybe someone can tell me something adequate? Or will I need to translate English documentation in order to implement and use this solution?
I will 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 and PHP for the server. It is necessary that the documentation was made for both server and client parts. By and large, nothing but kosher does not prevent the use of two different documentation generators. But I want to, so that both parts of the project were treated the same. I do not want to have a different appearance of the documentation for different parts of the same project. Plus, they certainly will have different syntax requirements, which is also not good.
The second problem is that the generators cannot parse the JavaScript code. I have almost chosen Doxygen , but as long as I do not teach my street javascript magic, I simply cannot use it. Of the alternatives was found such an animal, as JsDocToolkit . 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 the OOP practically does not use the OOP. But in any case, plans for refactoring the server side using OOP have been hanging for a long time. Perhaps even on python. So over time, this problem will disappear as well. Especially since the modular structure is there now. Problems in refactoring should arise.
')
Summarizing. Having rotated on their various representatives, I stopped on Doxygen. If you believe promises, you can configure it to work with languages that it does not support. Plus, by itself, it looks more powerful than other developments, which gives rise to hope for its flexibility.
Unfortunately, power and flexibility mean only one thing - surely Doxygen is very difficult to master. And I also need to explain why this is all necessary and why it cannot be done in a simpler way. Having tried to find some Russified site about Doxygen, I could not find anything like that. Maybe someone can tell me something adequate? Or will I need to translate English documentation in order to implement and use this solution?
I will report on the results of the implementation :)
Source: https://habr.com/ru/post/48423/
All Articles