Project docs: PasDoc vs. FPDoc
Closed this issue · 4 comments
I'd like to suggest to use PasDoc instead of FPDoc for our project, as PasDoc is reading in the comments directly from the source code and generating the docs from this. For FPDoc we would have to maintain a separate description file.
Using FPDoc means we would need to cut out the comments and transfer them into the description file (additional work). This means for the user also, he/she HAS TO look at the documentation files to get what a function is doing or returns, etc, Or, if we decided to keep the original comments in the code also (what I prefer), then we had to maintain/synchronize both, the comments in the source code and in the description file (additional work).
On the other hand, if we used PasDoc, we just keep the comments as they are. Some C-editor tags like \sa could be directly transformed into @seealso and voila.
What do you think?
My main argument for going with FPDoc is that it's the tool used by FPC and Lazarus; I suppose most Pascal programmers would be familiar with the HTML documentation as generated by that tool. I've never heard of PasDoc before, but looking at the example on the website... it's quite "eh", but acceptable.
I suppose that if we want to keep the amount of extra work to the minimum, then PasDoc would be the better choice, especially since - as you mentioned - we could just leave the comments almost as-is, needing only to change the \tags and maybe sort out some other warts.
While we're at it, I want to bring up the issue of generating + hosting the docs. For hosting, we could use GitHub pages, since it's a free and easy-to-use solution. For generating the docs, we could try doing it during CI (obviously, fired only on push to master and not on pull requests). I suppose this would be best done by having a separate repository and a "bot" user, i.e.:
- install fpc
- compile PasDoc
git clonethis repo- run PasDoc to generate docs
git clonethe GHPages repo- copy the generated docs
- create a new commit with the updated docs
- use the bot's credentials to push the changes
My main argument for going with FPDoc is that it's the tool used by FPC and Lazarus; I suppose most Pascal programmers would be familiar with the HTML documentation as generated by that tool. I've never heard of PasDoc before, but looking at the example on the website... it's quite "eh", but acceptable.
I see completely where you are coming from. - About the "eh"-factor of the generated pages: There are some possibilities to enhance the optics (e. g. a css stylesheet file). Maybe we could tweak this, too.
I suppose that if we want to keep the amount of extra work to the minimum, then PasDoc would be the better choice, especially since - as you mentioned - we could just leave the comments almost as-is, needing only to change the
\tagsand maybe sort out some other warts.
Absolutely!
While we're at it, I want to bring up the issue of generating + hosting the docs. For hosting, we could use GitHub pages, since it's a free and easy-to-use solution. For generating the docs, we could try doing it during CI (obviously, fired only on push to
masterand not on pull requests). I suppose this would be best done by having a separate repository and a "bot" user, i.e.:* install fpc * compile PasDoc * `git clone` this repo * run PasDoc to generate docs * `git clone` the GHPages repo * copy the generated docs * create a new commit with the updated docs * use the bot's credentials to push the changes
I like the idea to auto-generate the docs very much. I wonder about the proposed workflow: Are the generated docs played back into our project repo's docs folder or are they kept only in the new docs-repo?
GitHub pages work by taking the latest commit from chosen repo and branch. If we were to auto-build docs in CI, then trying to put them in the project's repo would mean adding commits in CI - which would make it easy to run into conflicts where we try to push some commits at the same time as the CI workflow does. Not to mention the fact that the CI would then need to distinguish between "real" commits and the "update docs" commits made in CI, lest we create an infinite loop of commit -> CI that makes new commit -> CI in reaction to new commit -> CI makes yet another commit -> yet another CI...
As such, I think it would be best to have a separate repo for the docs. Keeping the HTML docs in this repo pretty much rules out auto-building them in CI.
I see.
We need to ask @AthenaOfDelphi to generate a new repo "SDL2-for-Pascal-Docs" or something then, right?