This bug report was migrated from our old Bugzilla tracker.

Reported in version: HG 2.0
Reported for operating system, platform: Other, x86

Comments on the original bug report:

On 2017-09-23 03:36:40 +0000, Mark Callow wrote:

Has the Wiki been updated for 2.0.6?

If so, it looks like the doxygen build is not including the new SDL_vulkan.h.

On 2017-09-26 03:01:45 +0000, Mark Callow wrote:

Looking more closely, it appears the documentation on the Wiki has not been updated for a very long time. Tokens that were added several release ago are not mentioned.

So I am going to change the title on this bug.

On 2017-09-26 22:09:10 +0000, Sam Lantinga wrote:

Yeah, the core developers haven't had time to update the wiki documentation, though we keep the header files up to date.

Would you like to help?

On 2017-10-02 10:29:31 +0000, Mark Callow wrote:

I started to do some due diligence before answering. I ran doxygen on the source files using docs/doxyfile. The result is very different from what appears in the Wiki and there are a lot of warnings in the doxygen log.

Are there any instructions for generating the Wiki version of the documentation? I didn't find another doxyfile.

If anyone is going to fix any of the items on the doxygen log a 2.0.6 branch will have to be created. I presume that won't be a problem.

On 2017-10-02 23:41:31 +0000, Sam Lantinga wrote:

The wiki is hand crafted documentation, which is why it's out of date.

There's a style guide for content available here:
http://wiki.libsdl.org/Contributing

On 2017-10-02 23:42:52 +0000, Sam Lantinga wrote:

BTW, I'm not opposed to switching to doxygen generated wiki documentation, if you'd like to tackle that project instead.

On 2017-10-04 01:08:37 +0000, Mark Callow wrote:

The duplication of the Doxygen comments and the Wiki clearly makes a lot of extra work so using Doxygen is preferable. The problem I have with that is that the default Doxygen output is designed for code maintainers or spelunkers not API users. On another project I have tried and, so far, failed to massage the output into a form suitable for API users.

The main issue is how to provide an API-user-focused table of contents or index, i.e. based on the function and macro names rather than file names. If anyone can point me at working examples of such, I'd be grateful. I might then be willing to take on the project.

Another issue is how to integrate the result into the rest of the Wiki documentation.

On 2017-10-04 03:48:40 +0000, Ryan C. Gordon wrote:

(In reply to Mark Callow from comment # 6)

The duplication of the Doxygen comments and the Wiki clearly makes a lot of
extra work so using Doxygen is preferable. The problem I have with that is
that the default Doxygen output is designed for code maintainers or
spelunkers not API users. On another project I have tried and, so far,
failed to massage the output into a form suitable for API users.

Just to add to this: the wiki is hard to use as an actual wiki (for anti-spam purposes, we manually approve write access for people, which I suspect drives away contributors that would fix small things, etc), and more importantly: we can't reasonably generate offline documentation from the current wiki in any meaningful way. I would like to fix these problems and then prefer the wiki as the canonical source of information, if I had to choose between a wiki or Doxygen.

I'm tempted to see if something like MediaWiki would work better, or if it would be a different set of problems instead.

--ryan.

On 2017-10-04 07:12:10 +0000, Mark Callow wrote:

(In reply to Ryan C. Gordon from comment # 7)

I would like to fix these problems and
then prefer the wiki as the canonical source of information, if I had to
choose between a wiki or Doxygen.

Over the years I have found that developers are much more likely to update the documentation when it is right there next to the code they are changing than if it is in a separate location. For that reason I prefer Doxygen, or similar, as the canonical source of API documentation.

The presence of Doxygen comments all over the SDL source certainly caused Jacob and I to similarly document our recent work on Vulkan support as we were working on it and not, if at all, after the fact.

I was surprised to hear the Wiki API documentation didn't come from the Doxygen comments. For the functions where I have looked at both, the content has been virtually identical.

we manually approve write access for people, which I suspect drives
away contributors that would fix small things, etc)

One solution for this problem is something like GitHub where potential contributors can propose pull or merge requests.

I'm tempted to see if something like MediaWiki

I'm not familiar with wiki implementations. Why would MediaWiki server software be better than the current software?

On 2017-10-04 10:39:00 +0000, Ryan C. Gordon wrote:

(In reply to Mark Callow from comment # 8)

Over the years I have found that developers are much more likely to update
the documentation when it is right there next to the code they are changing
than if it is in a separate location. For that reason I prefer Doxygen, or
similar, as the canonical source of API documentation.

I agree, but it's also worth noting that documentation is read thousands more times than it is written (especially for SDL, where I'm constantly bombarded with requests for more documentation, references, books, etc), so optimizing for how users will consume it might be more important than how developers produce it.

I was surprised to hear the Wiki API documentation didn't come from the
Doxygen comments. For the functions where I have looked at both, the content
has been virtually identical.

I think there was a push for Doxygen support at one point, and it's just generally good practice to write headers like that. The wiki almost certainly started as a cut-and-paste of what was in the headers, too.

I'm not familiar with wiki implementations. Why would MediaWiki server
software be better than the current software?

I don't know if it is, but (being the software that drives Wikipedia) I'm wondering if it has more development resources behind it, for features as well as a nicer look/feel. It's just an idea, though; it might turn out to be a maintenance nightmare, etc.

--ryan.

On 2017-10-04 16:28:32 +0000, Sam Lantinga wrote:

We looked at MediaWiki years ago and chose the current solution instead, for reasons I forget, and that may not matter now. If we move to a new wiki solution, we'd need to figure out how to migrate the tons of existing non-API content.

It is possible to generate offline documentation for the current wiki, I just haven't done it since the last server move:
https://moinmo.in/HelpOnMoinCommand/ExportDump/

On 2017-10-05 02:43:04 +0000, Mark Callow wrote:

(In reply to Ryan C. Gordon from comment # 9)

I agree, but it's also worth noting that documentation is read thousands
more times than it is written (especially for SDL, where I'm constantly
bombarded with requests for more documentation, references, books, etc), so
optimizing for how users will consume it might be more important than how
developers produce it.

I agree, hence my remarks about generating an API-user-focused version from the Doxygen comments. I believe this is possible and I'm willing to give it a try but before I spend the time, I'd like an assurance that, if successful, you'll use it and not insist on moving the content to or duplicating it in a wiki.

For me, API-user-focused means that the table of contents and index will be based around function, macro, structure and enum names, similar to the current Wiki though the format might be different, e.g. in a sidebar. I don't think whether it is served from a wiki or a more static web server really matters to the readers.

For letting users provide corrections etc, and as a bonus aid software development, I would suggest installing GitLab Community Edition on your source repo server but, as you're using Mercurial, that is not an option. There is hglab but it is not open source and is Windows only so I don't know if that would be suitable either. Another possibility may be a mirror on GitHub using hg-github. (https://github.com/stephenmcd/hg-github).

On 2017-10-06 23:40:50 +0000, Sam Lantinga wrote:

I'm fine with integrating doxygen output into the wiki, since clearly we don't keep up with the API content. I'd like to keep the other useful content though, examples and intro and such.

On 2017-10-09 09:30:48 +0000, Mark Callow wrote:

Okay. I'll take a stab at producing an API-user-focused version of the Doxygen generated docs.

On 2017-10-09 19:44:12 +0000, Sam Lantinga wrote:

Great, thanks!