Hello fellow developpers / contributors
Where should we put the documentation for the functions? In the .h oder in the .cpp ? We should agree on this and try to do all the same.
When working on the code, we should all try to add little by little documentation and even comments to the existing functions. This way we might get a better doxygen documentation over time.
If you have other thoughts on conventions we could discuss them here.
Personally, beyond whatever other docs are done, I think that the schemas should be documented in-line, as anyone working with measurement or pattern files would have to go there first to understand their contents and format.
do you mean “on-line”? I am not sure what you mean by “in-line” in this context.
If you are saying that documentation about the structure of the xml files belongs IN the xml files, I disagree.
That’s a tricky one… Having just dealt with the mesurement schema, I don’t think it should be documented in the xml schema files. It should be documented somewhere though how the schema files interact with the various file versions. Would have saved me hours.
Having looked up XML comments, yeah, probably not the best idea to do in-line (i.e. putting a comment by each relevant line.) I did create a wiki page with links to what would probably be what you are talking about.
Has anyone of you a suggestion? I think the .h files are the better place.
Since we have multiple programmers, and over time the programmers may change, we need the comments to be close to the code. So the answer is in both the header(.h) and source (.cpp) files.
“.h files be used for templating and class definitions, while .cpp files are used for implementations and source code.” what is the difference between header and source files C++? - Stack Overflow
“Put the documentation where people will read and write it as they are using and working on the code.
Class comments go in front of classes, method comments in front of methods.
That is the best way to make sure things are maintained. It also keeps your header files relatively lean and avoids the touching issue of people updating method docs causing headers to be dirty and triggering rebuilds.” documentation - Where to put the doxygen comment blocks for an internal library - in H or in CPP files? - Stack Overflow