mn416 / QPULib

Language and compiler for the Raspberry Pi GPU
Other
430 stars 63 forks source link

On generating technical documentation for source code #39

Closed wimrijnders closed 6 years ago

wimrijnders commented 6 years ago

@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 6 years ago

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

mn416 commented 6 years ago

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 6 years ago

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.

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.

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