From 2ea1ea1011060ec5ce2e61ae0e6c689ea811e1c7 Mon Sep 17 00:00:00 2001 From: SDL Wiki Bot Date: Sat, 13 Sep 2025 00:23:10 +0000 Subject: [PATCH] Sync SDL3 wiki -> header [ci skip] --- docs/README-documentation-rules.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/README-documentation-rules.md b/docs/README-documentation-rules.md index 02809e2bba..2a4d96f1ad 100644 --- a/docs/README-documentation-rules.md +++ b/docs/README-documentation-rules.md @@ -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