mirrors/SDL
1
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2026-01-02 11:32:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

Sync SDL3 wiki -> header

Browse Source 
[ci skip]
This commit is contained in:
SDL Wiki Bot
2025-09-13 00:23:10 +00:00
parent 411e47ba00
commit 2ea1ea1011
1 changed files with 17 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
docs/README-documentation-rules.md
View File

@@ -274,6 +274,23 @@ comment. So don't mention the type a second time in the documentation if
possible. It looks cluttered and repetitive to do so.
## Keep `\param` and `\returns` sections short.
These strings end up in a table that we don't want to be bulky.
Try to keep these to one sentence/phrase where possible. If you need more
detail--even extremely common details, like "you need to free the returned
pointer"--put that information in the general Remarks section, where you
can be as verbose as you like.
(One exception for SDL: the return value almost always notes that on error,
you should call SDL_GetError() to get more information. The documentation
is so saturated with this that it's just the standard now.)
Convention at the moment is that pointer params that are permitted to
be NULL, which is somewhat uncommon, end with terse "May be NULL." sentence
at the end, and pointers that must be non-NULL (most of them) say nothing.
This is fine.
## Code examples go in the wiki.
We don't want the headers cluttered up with code examples. These live on the