mn416/QPULib

On generating technical documentation for source code

Closed this issue · 3 comments

wimrijnders commented

@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 commented

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

mn416 commented

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 commented

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.