The SDL3 Documentation Megathread

[icculus]

Ok, so one thing we'd like to do as SDL3 is getting closer is improve documentation.

Documentation is a never-ending job: it will never be complete and it can always improve, so we should probably decide on things we definitely want to do as specific tasks we can finish. Maybe we choose new tasks later, but let's have something we can list in a milestone.

This thread is open to conversation! I'll edit this text with a checklist when we make some decisions.

[icculus]

Some things I'm planning to do in the near-term:

• [x] Make the wiki bridge support #defines, enums and structs, instead of just functions. That's going to go a long way, as far as formal documentation is concerned.
• [ ] Make a YouTube video where I upgrade DirkSimple from SDL2 to SDL3.
• [ ] Make a YouTube video where I upgrade ioquake3 from SDL2 to SDL3.
• [x] Go through all the SDL3 wiki pages and clean out obsolete stuff: move everything to Markdown, delete pages for APIs that were removed/renamed, SDL2-specific pages, the old migration guide. SDL2's subdir I'm probably going to leave alone, but it could probably stand some weeding too.
• [x] Clean out stuff in the wiki that still says "DRAFT"
• [ ] Write documentation for each wiki Category.
• [ ] We have to decide if we want to write a less-formal migration guide. Right now I'm on the fence about it, to be honest.
• [ ] Synchronize wikheaders.pl across satellite libraries automatically.
• [ ] Provide a quick reference card thing.
• [ ] Add a wiki page about expected compiler support (C99, etc).
• [ ] Have some official examples.

[slouken]

Can you add wiki bridge support for hints as well?

[icculus]

Can you add wiki bridge support for hints as well?

I think they'll probably come with the #define support, but if not, yes, we can add that.

[icculus]

Make a YouTube video where I upgrade DirkSimple from SDL2 to SDL3.

Something like ioquake3 might be cool too, while I'm thinking about it.

[slouken]

Yeah, something people can actually build and run without ripping a laserdisk might be nice. :)

[icculus]

Spent the weekend working on the wiki bridge. Now it can do structs, unions, enums, and macros.

I'm still tweaking the code, but now this is also causing a big task of cleaning up stuff that was already written for the wiki for some of these things. I'm merging documentation where it's reasonable, throwing a lot of it out as obsolete or just bad, and converting from mediawiki to markdown format.

But progress is being made!

[Svintaj]

I would like to see a tutorial on a 'recommended cross-platform workflow'.

That show how to build a basic SDL3 example to Linux, Windows, macOS, Android and iOS. So a new SDL3 user can have a smooth working cross-platform workflow from start.

I think there is more people like me that know some C++ but not much about cross-platform compiling. I guess you, the SDL3 developers are kind of experts on cross-platform workflows and could give us some good advice, for a smooth path forward. 👋

[icculus]

I would like to see a tutorial on a 'recommended cross-platform workflow'.

Strictly speaking, this is what https://github.com/libsdl-org/SDL_helloworld is for, but it could use some more love.

[Svintaj]

it could use some more love

Ok, yes please, for me it is still like a riddle to decipher. 🤔 I would like more explanations on how and why. Preferably in a video tutorial! 🌞

I got a bunch of basic questions like: What am I supposed to do with this Hello World repository, to build main.c for different platforms than the one I’m currently on? What is ‘CI’ or ‘GitHub Actions’ and are they essential for cross-platform compiling? What shall I do with the .yml file? How should I modify the CMakeLists.txt file. Etc.

In the tutorial, pretend to explain the process for someone that only have learned plain C or C++ through a book. -> What more do someone need to learn in that case, to be able to cross-compile?

Since it’s a Hello World example for a Cross-Platform lib, I think it’s worth explaining it from the ground up. 🤓👍

[icculus]

Okay, I'll see if I can make a quick video for that!

[icculus]

I'm still tweaking the code, but now this is also causing a big task of cleaning up stuff that was already written for the wiki for some of these things. I'm merging documentation where it's reasonable, throwing a lot of it out as obsolete or just bad, and converting from mediawiki to markdown format.

The first wave of this is done now. I'm going to push this in the morning, so I'm alert in case it blows up the wiki server or something.

[icculus]

Pushed!

[madebr]

Since SDL3, CMake installs man pages. These man pages are generated using the perl script. Because the wikiheaders project is not available, the man pages don't contain eventual examples present in the wiki. Perhaps the bridge should also transfer example code to the SDL project?

[icculus]

This is intentional since it clutters up the headers, and honestly most example code you'd write for a single function is very close to useless, imho.

[madebr]

That's a valid point, and I agree. I was thinking about storing it somewhere in structured (testable) form

[sezero]

/home/runner/work/SDL/SDL/include/SDL3/SDL_pixels.h:710:25: error: not a Doxygen trailing comment [-Werror,-Wdocumentation]
    int ncolors;        /*< number of elements in `colors`. */
                        ^~~
                        /**<
/home/runner/work/SDL/SDL/include/SDL3/SDL_pixels.h:711:25: error: not a Doxygen trailing comment [-Werror,-Wdocumentation]
    SDL_Color *colors;  /*< an array of colors, `ncolors` long. */
                        ^~~
                        /**<
/home/runner/work/SDL/SDL/include/SDL3/SDL_pixels.h:712:25: error: not a Doxygen trailing comment [-Werror,-Wdocumentation]
    Uint32 version;     /*< internal use only, do not touch. */
                        ^~~
                        /**<
/home/runner/work/SDL/SDL/include/SDL3/SDL_pixels.h:713:25: error: not a Doxygen trailing comment [-Werror,-Wdocumentation]
    int refcount;       /*< internal use only, do not touch. */
                        ^~~
                        /**<
4 errors generated.

[icculus]

Generic typedefs (if they have a Doxygen-style comment right above them, mind you) are bridged to the wiki now. A lot of these are useful in the name of completeness, but it's super useful for things like this:

https://wiki.libsdl.org/SDL3/SDL_AudioStreamCallback

[madebr]

Can your documentation bot also synchronize wikiheaders.pl across the satellite libraries? e.g. build-scripts/wikiheaders.pl for SDL_image

[icculus]

Probably. I'll take a look.

[Sackzement]

Just wanted to throw this in here. This is my reference for SDL. Maybe it can give you some ideas.

Edit: I created this in LibreOffice Calc. Just checked how it looks in Excel and it's all white and almost unreadable. The reason seems to be, that if you use styles and style-inheritance, Excel doesn't recognize the default style, if it's modified. Here is the second version of the reference, where this is fixed: SDL3.2.0 Reference.ods

[icculus]

Can your documentation bot also synchronize wikiheaders.pl across the satellite libraries?

Against my better judgement, I took a run at SDL2's docs so it can use the latest wikiheaders.pl too. This was tedious, but resulted in cleaning out a ton of garbage.

More or less, I did a much faster version of the cleanups I already did in SDL3 (hours, not days). I've likely made some small mistakes, but hopefully this improves things from what was there.

But if anyone sees something obviously broken in the SDL2 headers or wiki, please either tell me or just push a fix.

[Sackzement]

An entry in the Wiki about which C standard is used by SDL could be useful. Something like:

C Standard:

Building a project with SDL: C89 and newer Building the SDL library itself: C99 and newer

And maybe a note about which C99 features are used to build SDL itself:

C99 features used to build the SDL library itself:

// comments variable declarations in the for loop init-clause va_copy function from (src/SDL_log.c) inline function specifier (in dbus-1.0 headers)

[icculus]

I added a little code to wikiheaders to tell me what we aren't covering right now. The output's not elegant, but it gets the job done.

I expected this to be a lot of things that the script doesn't document, but it turns out, we can turn almost any piece of the SDL headers into a wiki page at this point, which is pretty wild.

So this ended up being a useful way to see what things are raw text that either have broken comments or lack documentation.

For those inclined to sift through it, I put a trimmed-down version in a gist:

https://gist.github.com/icculus/565ba73ad134ede12905b26792963693

Some of this can be ignored (\file comment blocks, include-once macro stuff, other preprocessor salsa), but it's pretty clearly shows what needs fixing up in the headers still. Not a lot, but there are a few things.

But the tl;dr on this: the wiki/header documentation work is basically almost done at this point. We can always improve existing documentation, but there is very little that isn't documented at all now!

[madebr]

This is bike shedding, but I see this warning message when generating the SDL man pages:

  Use of uninitialized value $brief in string at /var/folders/3m/p59k4qdj0f17st0gn2cmj3640000gn/T/setupsdl/66c57facf1111a4ec08d3d1abdf3c87f3062ffbea8d9eb4c9c412e9b5e7f59b7/source/build-scripts/wikiheaders.pl line 1902.
  Use of uninitialized value $brief in string at /var/folders/3m/p59k4qdj0f17st0gn2cmj3640000gn/T/setupsdl/66c57facf1111a4ec08d3d1abdf3c87f3062ffbea8d9eb4c9c412e9b5e7f59b7/source/build-scripts/wikiheaders.pl line 1902.

ci link

[icculus]

Manually cleaned out that gist so it's only things that are at least worth considering (and maybe ignoring), or need simple fixes. The most obvious things that could do better in wikiheaders itself are documentation for properties (which I'm inclined to group with some other page, as we currently do for #defines right below a typedef), and the \file comment blocks, which honestly should bridge to various Category pages on the wiki.

I'll look at the perl warning in the morning, it looks like it's only macOS's perl doing it, but it's probably a legit bug in my code.

Also: this came up today: we shouldn't generate the manpages by default. Most people don't need them, and they add time and requirements to the build process. Plus, they require a case-sensitive filesystem, since at a minimum we have unrelated SDL_Log and SDL_log functions.

Let's make it easy for the things that need them (package maintainers, the true Unix devotees, and GitHub Actions) to turn them on with a CMake variable, but let's default building manpages to off.

[madebr]

Makes sense. I'll do that.

[icculus]

Properties now go to the wiki: https://wiki.libsdl.org/SDL3/SDL_CreateWindowWithProperties

[slouken]

Properties now go to the wiki: https://wiki.libsdl.org/SDL3/SDL_CreateWindowWithProperties

I suggest not including all the #define lines. Applications should be using the names of the properties, not the raw strings. Also maybe we don't need to create individual files for each property, unless that's useful for search or something?

[icculus]

I suggest not including all the #define lines.

I was torn about that, but I am absolutely certain all these scripting language bindings that are banging on our door all the time will appreciate knowing the actual string.

(and we can't change the strings later anyhow, since it would break ABI, so if someone ignores the macro and uses the string...)

unless that's useful for search or something?

They will come up in a search on the wiki itself (which is useful if the function docs don't directly mention it), but also I think it's nice for people to be able to say "what the heck is this thing?" and either punch it into the address bar on wiki.libsdl.org, or find that page on a Google search, without us having to write repetitive documentation for them.

[icculus]

Updated the gist; the remaining documentation gaps are:

• [x] function pointer typedefs that are split over multiple lines are currently ignored and shouldn't be.
• [x] the main callbacks are documented but the SDLMAIN_DECLSPEC symbol makes them get ignored by the script.
• [ ] SDL_stdinc.h, which is daunting if we want to get into it, which maybe we don't right now.
• [ ] The SDL_THREAD_ANNOTATION_ATTRIBUTE stuff, which I think we'll leave undocumented.
• [ ] SDL_PixelFormatEnum and SDL_Colorspace, which are gigantic but don't need a lot of documentation.
• [x] Bridging the \file stuff to the Category pages.
• [ ] Things like SDL_NORETURN and SDL_FORCE_INLINE in SDL_begin_code. Less important, not sure we intend apps to be using these directly anyhow.
• [ ] SDL_intrin.h probably doesn't need all the SDL_SSE_INTRINSICS macros documented, same reason.
• [ ] SDL_platform_defines.h, which is probably not worth documenting platform-by-platform.
• [ ] SDL_pen.h needs several adjustments from /**< one liners */ to documentation above the thing.
• [ ] A couple other legitimate things here and there, like SDL_IOStatus, etc.
• [ ] Fix the undefined variable warning on macOS.

I can feel myself petering out on this work, so I'm going to try to wrap this up tomorrow and get back to other tasks. After that, we should leave this issue open for later, but I think we're at the point where we have what amounts to a pretty thorough reference manual of the entire library.

We should have wikiheaders generate LaTeX and publish it, lol.

[slouken]

I suggest not including all the #define lines.

I was torn about that, but I am absolutely certain all these scripting language bindings that are banging on our door all the time will appreciate knowing the actual string.

Sure, but they can look in the header, this shouldn't be on the wiki. It's verbose and redundant with the documentation below it.

[icculus]

Sure, but they can look in the header, this shouldn't be on the wiki. It's verbose and redundant with the documentation below it.

Done in 77f4ffcc79fa35bb76de745f8e994ad5797cf978.

This won't show them in https://wiki.libsdl.org/SDL3/SDL_CreateWindowWithProperties, but it still generates the "go look at this function for details" pages, like this one: https://wiki.libsdl.org/SDL3/SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN

[slouken]

Perfect, thanks!

[icculus]

We should have wikiheaders generate LaTeX and publish it, lol.

I was joking when I said this, but I have to say...I don't hate it.

test.pdf

[slouken]

We should have wikiheaders generate LaTeX and publish it, lol.

I was joking when I said this, but I have to say...I don't hate it.

test.pdf

Yeah, that doesn't suck!

[icculus]

The test.pdf was just one of the wiki pages pushed through pandoc, but I spent a little time to make wikiheaders actually spit out LaTeX directly, and it was informative:

SDL-3.1.2-reference-manual.pdf

First, this could never go forward because it would need an enormous amount of manual labor to make it friendly to a book's dimensions. A lot of it works, but there are too many places where preformatted text and code blocks blow up and run off the end of the paper. I suspect fixing this isn't going to be a script thing, it's going to be hand-editing documentation to be less nice for the places we actually care about it: the wiki, the headers.

Second, we could probably format this more tightly with some different parameters, but holy moly, it's a SIXTEEN HUNDRED PAGE BOOK. No one is ever going to print this. Or lift it. With just the functions and no macros or datatypes, it's still like 1200 pages as-is.

(The PDF is still pretty cool, though.)

[icculus]

Now-bogus pages for removed/renamed APIs have been removed from the wiki (94 of them, total). All the old MoinMoin syntax is gone now, too, I think.

SDL2's wiki is still a disaster. Just so much bitrot to clean out of there, but I don't know if anyone will ever do it.

[slouken]

SDL2's wiki is still a disaster. Just so much bitrot to clean out of there, but I don't know if anyone will ever do it.

Nope, let's focus on SDL3. :)

[icculus]

Nope, let's focus on SDL3. :)

Agreed. I cleaned out some obvious messes real quickly, but there is a ton of documentation we wrote for SDL3 that would be an signficant effort to reproduce for SDL2.

That being said: I'm sorting through all the open issues on sdlwiki, and almost all of them so far were already fixed by wikiheaders, since it cleaned out a bunch of weird things and made everything look uniform. Most of the rest of the issues will be fixed when I made it automatically categorize pages by subsystem.

So I think SDL2's docs will have gaps (because no one wrote some pieces at all), but the wiki won't be unusable.

[icculus]

Also discovering from the unmerged sdlwiki pull requests how much duplicated labor we're avoiding with wikiheaders going forward. This was definitely a win.

[icculus]

Okay, cleaned out most of the sdlwiki issues and pull requests. There's a few still open I don't know how to respond to yet, but that's like a 2-year backlog cleared out.

It showed that category management is clearly the biggest pain point, both for editors and readers, and also the one most obviously fixable by adding it to wikiheaders, so that's my next task.

[icculus]

Wrote up some documentation on how to write documentation. It just sort of explains the quirks wikiheaders uses to make things work, so when things break I can point to a section to explain why.

https://wiki.libsdl.org/SDL3/README/documentation-rules

(or docs/README-documentation-rules.md)

[slouken]

Wrote up some documentation on how to write documentation. It just sort of explains the quirks wikiheaders uses to make things work, so when things break I can point to a section to explain why.

https://wiki.libsdl.org/SDL3/README/documentation-rules

(or docs/README-documentation-rules.md)

Wow, this is really good documentation documentation. Thanks!

[icculus]

Ran across this, worth considering:

https://blog.theprogrammingjunkie.com/post/sdl2-cheatsheet/

[icculus]

Okay, the category documentation work is done!

Now people might start at...

https://wiki.libsdl.org/SDL3/APIByCategory

...and find the audio section, clicking through to...

https://wiki.libsdl.org/SDL3/CategoryAudio

Where they'll get a quick overview, and then a list of everything in the category. This should make it easier to navigate through to what they need.

And of course, it's bridged to the headers. :) For the most part, one header is one category on the wiki, so the mental grouping is the same.

A lot of these categories need documentation written, as most have one-sentence placeholders. But all the code and cleanup is in place now.

This was the last big pending task on wikiheaders, fwiw. :)

[madebr]

Nice job!

Is the 2px padding required on code items? That makes the first line to be indendented a bit. For example, see the code block at https://wiki.libsdl.org/SDL3/CategoryAudio

(My browser is firefox)

[icculus]

That's probably a CSS bug. We can fix that, I assume.

[icculus]

Pushed a fix for the CSS. Note that firefox caches the CSS for the wiki really aggressively, and I'm not sure why. I ended up hitting F12, finding the "network" tab and clicking "disable cache" before reloading the page to get it to catch up...but with the right CSS, it's definitely fixed here.

[madebr]

I think caching can be sidestepped by adding (dummy) query strings to the url. e.g. https://wiki.libsdl.org/static_files/ghwikipp.css?h=026e7d33 And calculate the query as the md5 hash of the file contents.

[icculus]

Example code is being discussed over in #10350.