Good idea, I just added it
Kunda1 wrote: ↑
Thu Jun 20, 2019 9:15 pm
Cool! Doxygen is a beast and we have quite a ways ahead of figuring out how we should document the FC code. Currently it's swiss cheese when it comes to API documentaion generated from within the code and there are mixed feelings about making the source code bloated by generating documentation this way. Maybe your approach can generate some consensus and even a convention around documenting ???
Yes the documentation is very sparse at the moment. Doxygen supports in code as well as embedding external documentation. Doing everything in the source blows up the code like you said but doing everything external is messy, hard to track and it's tedious to read the code together with the documentation. I think the best way is to combine both approaches. Documentation of members definitely belong in the source code but descriptions with examples and so on of classes, namespaces or modules could be moved out into a separate file.
Like you said the most important (and most challenging) thing is that the approach is consistently used on every part of FreeCAD. I definitely think that source documentation can't be substituted by wiki articles and if done right it's very easy to use (for both developer and user). Because writing tests is not really meaningful without stating what the function is supposed to to I'm going to write a lot of documentation. Lets see how my approach of documenting evolves during GSoC and maybe if it's received well by the community we can take parts or all of it for all of FreeCAD