On generating technical documentation for source code

[wimrijnders]

@mn416 I did a test run with doxygen over the code in Lib. I put the result on my webserver for your perusal: QPULib documentation.

The thing is, it's very sparse, because no comments are actually present at the moment. Just about the only commented thing is Kernel::pretty(), which I added.

So, I'm actually wondering if this is useful at all. It only makes sense if we consistently add the comments. I honestly don't feel like doing this; I would prefer to add comments as I go, to document the understanding of the code as I see it right at that moment. I'm expecting that you don't want to add comments retroactively either.

I propose to just skip the document generation for now. I will put it as a long-term item on the TODO. Is this OK with you?

[wimrijnders]

Note: I'm not keeping the demo documentation on my webserver forever. Will remove it when this issue closes.

[mn416]

Hi @wimrijnders,

Thanks for looking at this. I agree, at this stage it's probably not that helpful due to lack of comments.
Still, some might find it useful, so you could include a script to generate these docs in the repo, if you wanted.

For this kind of informal project, I think time is better spent on illustrative examples rather than exhaustive commenting.

[wimrijnders]

OK agreed then, let it pass. It's actually not much work to add the documentation generation, can always do it later.

For this kind of informal project, I think time is better spent on illustrative examples rather than exhaustive commenting.

I sort of disagree with you here.

• Yes this is an informal project. My wish is to turn it into an industrial-strength project.

Everything I'm doing now is to that goal, I want it to be battle proof. I hope you don't regard that as a conflict of interest. I have faith in QPULib, and I feel that it deserves more usage. This is my way of getting there.

• More documentation is always good and required here. This isn't your average hack, it's a pretty sophisticated piece of software.
• However, it doesn't need to be exhaustive, I agree. I'm aiming for 'complete enough to do something useful'.
• And again 'exhaustive': I see no need right now to fill in all the blanks for the technical documentation. I will do this as I go and I hope you will too. Once a certain threshold is reached, we can reconsider adding documentation generation.

Closing this issue, we're not going to work on it right away.