Style Guide: Function Pages
This guide provides specific instructions for editing or adding your own content to each section of a Function page in this wiki.
Function pages should provide basic information about the SDL functions to allow users to most effectively utilize them in their projects.
Contents
General Guidelines
red |
Please observe the following for all function pages:
- Do not post anything that you do not have permission to post publicly.
- Sections should have adequate details to make them clear and useful while remaining brief wherever possible. Code Examples and Remarks may be more extensive than other sections if necessary.
- Please remember to keep it accurate, simple, and easy to understand.
Do not remove, modify, or add to the markup above the page title (#pragma or #acl processing instructions, etc.) except:
On CategoryCompat pages, place the following markup above the page title, below the processing instructions or red markup if present:
||<tablewidth="100%" #000000 style="color: #FF8C00;" :> <<BR>>~+For Backward Compatibility Only+~<<BR>><<BR>> ||
- Do not remove, modify, or add section headings unless specifically mentioned below.
- In general, we prefer that you do not remove or modify existing content unless it is clearly incorrect or out of date.
Pages with red at the top are in progress and will often contain unusual content, formatting, or notes. Please do not remove or modify these. That will all be corrected/removed upon final edit.
Getting Started
Begin by going to the page you wish to edit and selecting blue or blue in the left column to begin editing.
Markup info provided here is specifically for use in the Text editor but should work in both.
- Scroll down in the edit window to the section(s) you want to edit. Add your content following the conventions in this style guide.
Find information relevant to your content in the style guide sections below and apply the appropriate formatting as you edit.
Preview your work as you go by clicking blue in the left column. Preview often and any time you are unsure of formatting.
(Keep in mind that a few things (like Color2 text) don't preview exactly as they parse.)
Save your work by clicking blue in the left column after you are satisfied with your content and have filled in the Comment field under the editing box.
For assistance with editing, saving, or wiki-appropriate markup see the Wiki Basics Style Guide or contact us at <ANTI SPAM wiki AT libsdl DOT org>.
Editing Specific Sections
Title
Do not edit the Title.
The Title section consists of the page heading and its markup:
= SDL_FunctionName =
For function pages this is the name of the function being described on the page and should match the address of the page.
Example: Page address http://wiki.libsdl.org/moin.cgi/SDL_CreateWindow should have matching title = SDL_CreateWindow = and describe the SDL_CreateWindow() function.
If you believe a change is necessary please submit Feedback from that page or contact us at <ANTI SPAM wiki AT libsdl DOT org>.
Description
The Description section immediately follows the page title and does not have it's own heading.
All function descriptions begin with: Use this function to
- or very rarely
Use this macro to
followed by a clear and concise description of what the function does.
Note: Information presented in this section is meant to be limited. Extended description information for more complicated functions should be placed in the Remarks section instead.
- The Description should not contain a link to the Remarks section even if additional information is located there.
If the page describes a macro rather than a function |
Action: Use the alternate description (Use this macro to...) and, if necessary, replace the word function with the word macro where appropriate throughout the page. |
Note: In some rare cases it has been deemed appropriate to refer to a macro as a function in the wiki. (eg: SDL_QuitRequested()) This is not accidental. Please do not "correct" these instances. If you feel strongly that a change should be made please contact us. |
|
Example: SDL_VERSION() |
|
If another API page is referenced in the description |
Action: Be sure to hyperlink it and use () outside the link markup if it is a function. |
Example: [[SDL_FunctionName]](), [[SDL_StructureName]], SDL_GetThreadName() |
|
If a parameter on that page is referenced in the description |
Action: Use bold for the parameter name. |
Note: This is a very rare occurrence. |
|
Note: If the reference is to the parameter as a concept (ie: the window to do something with) rather than directly to the parameter itself (ie: SDL_Function(window)) do not make it bold. |
Table of Contents
Do not edit the Table of Contents.
The Table of Contents consists of the following markup and is generated automatically on the parsed page.
<<TableOfContents()>>
If you believe a change is necessary please submit Feedback from that page or contact us at <ANTI SPAM wiki AT libsdl DOT org>.
Syntax
The Syntax section consists of a code box that displays the basic components of the function using some specific formatting conventions. Please apply the following conventions when editing this section.
The basic format is as follows:
{{{#!highlight cpp returnType* SDL_FunctionName(type1 parameter1, type2* parameter2, ... typeN parameterN) }}}
red All types and parameters should be vertically aligned.
Spacing for parameter types is left-aligned to the type on the first line.
Spacing for parameters is left-aligned to the longest param type so that there is only 1 space between the longest type (with any pointers) and its parameter.
Pointers (*, **) should be aligned next to the types (no space between) and should have at least one space following.
Markup: Use spaces as necessary to create the correct alignment. Within a code box spacing is fixed-width.
Note: To be omitted
All additional text that may be found in the header or elsewhere, such as extern, SDLCALL, etc.
The space between SDL_FunctionName and (.
- Ending semi-colon (;)
Note: To be included
The code box and colorizing markup above and below the function syntax
{{{#!highlight cpp
}}}A single space between returnType and SDL_FunctionName
- Commas at the end of each line before the last if there is more than 1 parameter
- The parentheses enclosing the parameters
Note: Do not remove or alter the code box markup surrounding the function syntax. The starting and ending markup must remain on separate lines above and below the rest of the content in order to generate the code box.
If a function refers to a callback function |
Action: See the special section on callback functions below. |
Note: Callback functions do not get their own pages. |
|
Example: SDL_AddEventWatch(), SDL_AddTimer() |
Example:
{{{#!highlight cpp 1 space no space spaces (as needed) | \ |_________| SDL_AudioSpec* SDL_LoadWAV_RW(SDL_RWops* src, int freesrc, SDL_AudioSpec* spec, <- longest type Uint8** audio_buf, sets alignment Uint32* audio_len) |||||||||||||||||||||||||||||| \ | spaces (as needed) no space 1 space }}}
Function Parameters
The Function Parameters section provides basic information about each parameter in the function and is presented in table format.
red
If the only parameter is void |
Action: Delete the entire Function Parameters section, including the header. |
Example: SDL_AllocRW() |
Otherwise, function parameters follow this basic format:
||'''parameter1'''||description|| ||'''parameter2'''||description|| ... ||'''parameterN'''||description||
Markup: Use basic table markup and enclose each parameter name in bold markup. All text in the table is left-justified.
The first column contains the parameter names, without types or pointers, in bold.
The second column contains a simple description of each parameter using some specific formatting conventions.
red All descriptions begin with a lower case letter, end without a period, and are generally not complete sentences.
- There are a few content-dependent conventions we have chosen for consistency across pages - see the tables below for details.
Example: SDL_SetColorKey()
Content-dependent formatting: General |
|
If more than one statement must be included in the description |
Action: Separate them with a semi-colon (;) |
Note: This should be avoided whenever possible. See "If a more detailed description is required to adequately explain a parameter" below for more details. |
|
Example: SDL_PixelFormatEnumToMasks() |
|
If a more detailed description is required to adequately explain a parameter |
Action 1 : Append the following, verbatim, to the end of the brief description |
Action 2: Place the more detailed information in the Remarks section. |
|
Action 3: See "If the Remarks section is large" below for more details. |
|
Example: SDL_CreateWindow() |
|
If the Remarks section is large |
Action 1: Create an anchor immediately before the additional comments you are adding to the Remarks section. |
Markup: Use <<Anchor(anchorname)>>, where anchorname is a name of your choosing, to create the anchor in the Remarks section. See Anchors for details. |
|
Action 2: Modify the Remarks link in the parameter description (see Action 1 in "If a more detailed description is required to adequately explain a parameter" above) to the following: |
|
If there is a pointer associated with the parameter |
Action: Avoid mentioning pointers unless they are critical to understanding the parameter or there is little other way to describe it (ie: void*) |
Example: SDL_SetColorKey() |
|
If a pointer points to something that is filled in by the function or that has been filled in |
Action: Use the phrase filled in with in the description |
Example: SDL_QueryTexturePixels() |
|
If the description mentions a structure that has a page |
Action 1: Use the following pattern to describe the parameter: |
Action 2: Check the table below for structure-specific phrasing. |
|
Note: Be sure to hyperlink the structure name as shown in Action 1 in the type and description columns (as appropriate) except if the row is greyed out (see If the parameter is for internal use, deprecated, or private for details). |
|
Example: SDL_UnionRect() |
|
If the description mentions a structure that does not have a page |
Action: Use the plain English term to describe the structure (ie: SDL_Window == the window) and omit the hyperlink. |
Note: Please check the current wiki before selecting this option for wording, as a page may have been created since this was written or since you last checked. |
|
Example: SDL_RenderClear() |
|
If the description mentions an enumeration |
Action: It is not necessary to specifically describe it as an enumeration as above for structures, but DO hyperlink if it has a page except if the row is greyed out (see If the parameter is for internal use, deprecated, or private for details). |
Example: SDL_PixelFormat |
|
If a description must refer to any other page in the API |
Action: Create a hyperlink to the page except if the row is greyed out (see If the parameter is for internal use, deprecated, or private for details). |
If the parameter is for internal use, deprecated, or private |
Action 1: Make the text in the row grey by including the following, verbatim, in the first cell of the row between the starting table markup and the text: |
Action 2: Include the reason (ie: internal use, etc.) in parentheses at the end of the description. |
|
Action 3: DO NOT hyperlink any related API pages (ie: structure type) on greyed out parameters. |
|
Example: ||<rowstyle="color: #808080;">'''param'''||description (reason)||, SDL_PixelFormat |
|
Note: Although a rare case, any other table style markup should be included within the same set of angle brackets (<>) and separated from this markup by a space. |
|
If a function refers to a callback function |
Action: See the special section on callback functions below. |
Note: Callback functions do not get their own pages. |
|
Example: SDL_AddEventWatch(), SDL_AddTimer() |
|
If a parameter references another parameter on that same page |
Action: Use bold for the parameter name. |
Note: This is a very rare occurrence. |
|
Note: If the reference is to the parameter as a concept (ie: the window to do something with) rather than directly to the parameter itself (ie: SDL_Function(window)) do not make it bold. |
|
Example: SDL_EnclosePoints() |
|
If a description is referring to something that could be any one of a group of similar items (ie: rectangles) |
Action: Begin the description with a/an |
Example: SDL_HasIntersection() |
|
Note: We realize that this is a somewhat arbitrary distinction depending upon your perspective. If you are unsure whether to use a/an or the it may be helpful to do a quick text search for other pages with the same or similar parameter and copy the format there. Ultimately, though, it's not worth losing sleep over. Just pick one. |
|
If a description is referring to a specific item from a group (ie: a specific window) |
Action: Begin the description with the |
Example: SDL_BlitScaled() |
|
Note: We realize that this is a somewhat arbitrary distinction depending upon your perspective. If you are unsure whether to use a/an or the it may be helpful to do a quick text search for other pages with the same or similar parameter and copy the format there. Ultimately, though, it's not worth losing sleep over. Just pick one. |
Note: It would only rarely be appropriate to use the exact same description of a common parameter every time that parameter appears in the API. However, the same or very similar description can be used for many occurrences of the same parameter, enhancing consistency across pages. The following table provides a list of these commonly used descriptions.
Action: When choosing a description phrase for a parameter please check this list to see if any of these common descriptions is applicable, even if a minor modification is required.
Content-dependent formatting: Specific |
|
If the parameter is SDL_Palette* palette |
Action 1: Most often this description begins with the [[SDL_Palette]] structure to, followed by what to do with the palette (ie: free, modify, etc.). |
Action 2: The most common version is the [[SDL_Palette]] structure to use |
|
Example: SDL_SetSurfacePalette(), SDL_FreePalette() |
|
Note: Of course other phrases to describe this parameter may become necessary. A text search for "SDL_Palette* palette" should provide you with other descriptions if they arise. |
|
If the parameter is SDL_Rect* rect(s) |
Action 1 - rect: Most often this description begins with the/an [[SDL_Rect]] structure representing the rectangle to, followed by what the rectangle is for (ie: fill, draw, intersect, etc). |
Action 2 - rects: When the parameter is plural it refers to an array of rectangles and will most often begin with an array of [[SDL_Rect]] structures representing the rectangles to, followed by what the rectangles are for. |
|
Example: SDL_FillRect(), SDL_RenderDrawRect(), SDL_IntersectRectAndLine(), SDL_RenderDrawRects() |
|
Note: Of course there are some other phrases to describe these parameters. A text search for "SDL_Rect* rect" should provide you with plenty of other examples of both the singular and plural parameters. |
|
If the parameter is SDL_Renderer* renderer |
Action: A rare exception (at least so far), this description is always the rendering context. |
red Please use the rendering context for all occurrences of this parameter unless/until it appears in the API in a different context that calls for another description. A text search for "SDL_Renderer* renderer" should be used to determine if this has become the case. |
|
Example: SDL_RenderPresent(), SDL_RenderDrawLine(), SDL_CreateTexture() |
|
If the parameter is SDL_Surface* surface |
Action 1: Most often this description begins with the [[SDL_Surface]] structure to, followed by what is happening with the structure (ie: optimize, be locked, etc.). |
Action 2: The most common versions are the [[SDL_Surface]] structure to update (often used with Set functions) or the [[SDL_Surface]] structure to query (often used with Get functions). |
|
Action 3: Some will be best described by the following instead: the [[SDL_Surface]] structure representing <something>. |
|
Example: SDL_SetSurfaceRLE(), SDL_LockSurface(), SDL_GetClipRect(), SDL_SaveBMP_RW() |
|
Note: Of course there are some other phrases to describe this parameter. A text search for "SDL_Surface* surface" should provide you with plenty of other examples. |
|
If the parameter is SDL_Texture* texture |
Action 1: Most often this description begins with the texture to, followed by what is being done (ie: create, destroy, etc.). |
Action 2: The most common versions are the texture to update (often used with Set functions) or the texture to query (often used with Get functions). |
|
Example: SDL_SetTextureAlphaMod(), SDL_QueryTexturePixels(), SDL_UnlockTexture() |
|
Note: Of course there are some other phrases to describe this parameter. A text search for "SDL_Texture* texture" should provide you with plenty of other examples. |
|
If the parameter is SDL_Window* window |
Action 1: Most often this description begins with the window to, followed by what is being done (ie: minimize, maximize, show, etc). |
Action 2: The most common versions are the window to change (often used with Set functions) or the window to query (often used with Get functions). |
|
Example: SDL_RestoreWindow(), SDL_SetWindowTitle(), SDL_GetWindowFlags() |
|
Note: Of course there are some other phrases to describe this parameter. A text search for "SDL_Window* window" should provide you with plenty of examples. |
|
If the parameters include fmt and ... |
Action: For fmt use a printf() style message format string |
Note: To date this is the only context for the ... parameter. If your case does not follow this pattern exactly it may be necessary to make some adjustments. Please keep them as minimal as possible while creating an accurate wiki entry. |
|
Example: SDL_SetError(), SDL_Log() |
Note: Please do not use Includes in this section. It may occasionally be appropriate to copy and paste the parameters and descriptions from one function to another (perhaps with minor changes). This is the preferred method over using an Include.
Return Value
The Return Value section provides basic information about what, if anything, a function will return upon success or failure.
red
If the return value is void |
Note: This is not the same as void*! See the table below for void* return values. |
Action: Delete the entire Return Value section, including the header. |
|
Example: SDL_FreeSurface() |
Otherwise, return values follow this basic format:
Returns <something> on success or <something else> on failure; call [[SDL_GetError]]() for more information.
Use the following tables to determine what to replace <something> and <something else> with in the standard statement above, and to determine whether some other action is required.
- Please check both tables.
Replacements by type |
|
If the return value is an int (0 or <0) |
Action: Use Returns 0 on success or a negative error code on failure; call [[SDL_GetError]]() for more information. |
If the return value is an int other than above or a float |
Action: Replace <something> and <something else> with the applicable numbers. |
Example: Returns 1 on success or 0 on failure; call [[SDL_GetError]]() for more information. |
|
If the return value is SDL_bool |
Action: Use Returns SDL_TRUE on success or SDL_FALSE on failure; call [[SDL_GetError]]() for more information. |
If the return value is a pointer or NULL |
Action:Replace <something> with an appropriate description of the pointer (usually leaving out any mention of the pointer, as in parameters) and replace <something else> with NULL. |
Note: See "If the return value type is a structure" below for more details. |
|
Example: SDL_HapticOpen(), SDL_GetRenderer() |
|
If the return value type is a structure |
Action: The general format will approximate: Returns an/the [[SDL_StructureName]] representing <what it represents>, for success. The failure statement will depend upon what is returned on failure, if anything. See other Ifs for options. |
Note: Ideally in this case, you would search for other functions using the same return value and replicate the phrasing of others as appropriate. (Example search: "returnValue SDL_", where returnValue is replaced with the value you are interested in.) |
|
Example: SDL_CreateRGBSurfaceFrom() |
|
If the return value is void* |
Action:See "If the return value is a pointer or NULL" above. |
Note: In most cases it will be appropriate to mention the pointer for void*. Ideally, look at other similar functions for guidance. |
|
Example: SDL_LoadFunction(), SDL_SetWindowData() |
|
If the return value type is a Uint |
Action: Replace <something> with a brief, appropriate description of the Uint. |
Example: SDL_MapRGBA(), SDL_WasInit() |
|
Note: Very rarely the Uint that is returned is a mask of enumerated values. See SDL_MasksToPixelFormatEnum() for an example of how to handle this. |
|
If the return value type is a char or const char |
Action: Replace <something> with a brief, appropriate description of the returned string. |
Example: SDL_GetCurrentVideoDriver() |
|
If there are more than 2 possible return values |
Action: Add any additional values following the applicable rules above. Keep the primary success and primary failure values first and last, respectively, or place them in some other logical order (such as numerical). |
Example: SDL_HapticOpened(), SDL_OpenAudio() |
|
If the function does not have a failure state |
Note: It is very rare for a function to be unable to fail. This option covers those rare cases only. |
Action 1: If the function only has 1 return value state: |
|
Action 2: If the function has 2 return values but they don't represent success and failure: |
|
Example: only 1 return state SDL_GetAudioDeviceStatus(); alternate return state SDL_QuitRequested() |
Replacements by other criteria |
|
If a parameter on that page is referenced in the return value |
Action: Use bold for the parameter name. |
Note: This is a very rare occurrence. |
|
Note: If the reference is to the parameter as a concept (ie: the window) rather than directly to the parameter itself (ie: window) do not make it bold. |
|
Example: SDL_LoadWAV_RW(), SDL_GL_CreateContext() |
|
If the return value mentions a structure that has a page |
Action: Use the following pattern to describe the return value: |
Note: Be sure to hyperlink the structure name as shown. |
|
Example: SDL_UnionRect() |
|
If the return value mentions a structure that does not have a page |
Action: Use the plain English term to describe the structure (ie: SDL_Window == window). |
Note: These structures may eventually have pages or other references worth linking to, in which case please follow the instructions above for linking to items with pages of their own. |
|
If the return value must refer to any other page in the API |
Action: Create a hyperlink to the page. |
If the page is for an enumeration it is not necessary to describe it as an enumeration as above for structures. |
Note: It is extremely rare that an Include is appropriate in this section. If it were to occur it would only be to provide a list of possible return values that are based on an enumeration (or similar). In that case, please see the instructions for creating an Include in the Wiki Basics style guide, and the Include section of the Remarks style guide for details.
If you use an Include in this section, please email <ANTI SPAM wiki AT libsdl DOT org> telling us what page received the Include and what page was used as the source. We are keeping a list of all pages using Includes for future reference and this will help us to keep this list up to date. We appreciate your taking time for this extra step to help us keep our records accurate and useful. Thank you!
Code Examples
The Code Examples section is meant to contain simple, meaningful examples of how to use the function in a program.
Unlike other sections, which should rarely require editing once DRAFT is removed, this section is expected to change over time.
This is one of the few sections that is intended to grow and adjust as users discover more information about a function that would be helpful to share with other users.
For the most part the contents of the Code Examples section will be user-generated and this section will remain as-is until users input their examples.
Please see the Code Examples Style Guide for details on editing this section.
Remarks
The Remarks section is meant to contain additional information that did not fit in the other sections as well as comments regarding the behavior and use of the function in real-world applications.
Unlike other sections, which should rarely require editing once DRAFT is removed, this section is expected to change over time.
This is one of the few sections that is intended to grow and adjust as users discover more information about how a function behaves under different circumstances.
For the most part the contents of the Remarks section will be user-generated and this section will remain as-is until users input their comments.
Note: This is not an appropriate place to post questions, suggestions, bugs, or commentary. Please use the other communication channels available to you, especially the forums and Feedback form, for these types of remarks.
Please see the Remarks Style Guide for details on editing this section.
Related Functions
The Related Functions section provides a list of other functions specifically referenced by that function or otherwise closely related to it.
In general, a "Related Function" is one that is important to the use or understanding of the given function.
This list should include:
- the opposite function in a function pair (ie: get/set, do/undo)
- functions that represent close alternatives (ie: general and specific versions, singular and plural versions)
- functions that are called by or otherwise very closely related to the actions of the primary function on the page
This list should not include:
- the primary function on that page
- every other function that might be considered "related"
An argument can usually be made for a "relationship" between many functions. Including all of them would make these lists much less valuable.
- all functions of similar type or action
- all functions of a related category
- functions that are indirectly related (ie: it might be common to use them together)
- functions that do not have a page in the wiki (usually because they are not public functions)
- non-functions (ie: do not include structures or enumerations in this list)
Note: In most cases a Related Function reference should be reciprocal - if you include function B on the page for function A then function A should be included on the page for function B.
Markup: Each line should begin with a single blank space and a period followed by the function name enclosed in double brackets to create a hyperlink.
Note: Do not include empty parentheses after the function names in this section. They are all functions so it should be understood/unnecessary.
The basic format for the Related Functions list is:
== Related Functions == .[[SDL_FunctionName]] .[[SDL_FunctionName]]
Note: The heading was included to more clearly illustrate the blank space before the period at the beginning of each list line. Without this markup the format will not parse correctly.
If there is more than one function in the list |
Action: List the functions in alphabetical order. |
If there are no related functions |
Action: This section may be removed entirely (including the heading) and added back at a later time if it becomes relevant. |
Note: Function pages do not include a "Related Structures" or "Related Enumerations" section as some of the other page types do. If there are important related structures or enumerations they are to be included in the body of the page as links (usually in the Function Parameters or Remarks section). If you feel it is critical that a distinct section for one of these groups be included on a specific function page please submit Feedback from that page or contact us at <ANTI SPAM wiki AT libsdl DOT org> to discuss it.
Footer
The Footer section consists of a horizontal rule followed by two links separated by a comma.
Markup:
---- [[CategoryAPI]], [[CategoryHeader]]
where CategoryAPI is the same for every function page and CategoryHeader is function-specific with Header varying based on the header file containing the function (see below).
red Category names do not always match the header file name. Please consult the following table for the correct name to use so the function will appear in the correct list(s).
Action 1: Do not edit the CategoryAPI link!
Action 2: The CategoryHeader link may be edited if the page still says [[CategoryHeader]] (as on a new page) or if the function has been relocated to another header (very rare).
red There are a few exceptions to this rule (pages with a category name that does not match their header file). These have been determined by the SDL team. Please do not change an existing page's category name simply because it does not match its header file. If you are concerned that a name is incorrect please submit Feedback from that page or contact us at <ANTI SPAM wiki AT libsdl DOT org> to confirm the change first.
Markup: Replace CategoryHeader with the appropriate category name from the table that follows, or contact us at <ANTI SPAM wiki AT libsdl DOT org> to find out what category name to use if you are unsure or if the category appears to be missing.
Header File Containing the Function* |
Corresponding Category Name |
SDL.h |
|
SDL_assert.h |
|
SDL_atomic.h |
|
SDL_audio.h |
|
SDL_clipboard.h |
|
SDL_bits.h |
|
SDL_cpuinfo.h |
CategoryCPU |
SDL_endian.h |
|
SDL_error.h |
|
SDL_events.h |
|
SDL_gamecontroller.h |
|
SDL_haptic.h |
|
SDL_hints.h |
|
SDL_joystick.h |
|
SDL_keyboard.h |
|
SDL_keycode.h |
|
SDL_loadso.h |
|
SDL_log.h |
|
SDL_mouse.h |
|
SDL_mutex.h |
|
SDL_pixels.h |
|
SDL_platform.h |
|
SDL_power.h |
|
SDL_quit.h |
|
SDL_rect.h |
|
SDL_render.h |
|
SDL_rwops.h |
CategoryIO |
SDL_scancode.h |
|
SDL_surface.h |
|
SDL_syswm.h |
CategorySWM |
SDL_thread.h |
|
SDL_timer.h |
|
SDL_version.h |
|
SDL_video.h |
|
*Some exceptions exist. See above. |
Special
This section contains details for special formatting circumstances that are best described separately from the average function page. In general these guidelines should be used in conjunction with the above.
Callback Functions
The presence of a callback function will affect two (2) sections of the main function's page - Function Parameters and Remarks.
Action 1: Use the following formatting specifics in addition to those listed for the main function above whenever a callback function is included on a function page:
Function Parameters Section Formatting Details |
|
For the parameter that refers to the callback function |
Action: Use the following wording, modified as necessary, to describe the parameter: |
Note: This parameter is often named callback but may have other names (such as filter, fn, or handler). |
|
Example: SDL_LogSetOutputFunction(), SDL_AddEventWatch(), SDL_CreateThread(), SDL_SetAssertionHandler() |
|
For the parameter that passes user data to the callback |
Action: Use the following wording, modified as necessary, to describe the parameter: |
Note: In rare cases, often 'Get' functions, this is a pointer to a pointer and should be described as such. |
|
Note: This parameter is often named userdata, but may have other names (such as data or param). It is important to distinguish this parameter from other parameters that are passed to the callback also, but that are not strictly carrying "user data" (such as interval) and from other parameters that are unrelated to the callback function (such as name). See below for details. |
|
Example: SDL_LogSetOutputFunction(), SDL_CreateThread(), SDL_AddTimer(), SDL_LogGetOutputFunction() |
|
For other parameters related to the callback |
Action: There may be other parameters that are passed to the callback function but which are sufficiently different from the user data concept that the wording above does not really apply. In these cases use a description that is appropriate. Often it will still be appropriate to include the phrase passed to '''callback''' in these descriptions. |
Example: SDL_AddTimer() |
|
For additional function parameters not related to the callback |
Action: Follow any applicable guidelines listed above |
Example: SDL_CreateThread() |
Action 2: Detail the syntax and parameters of the callback function in the Remarks section using the following basic format with the changes listed in the table below:
The function prototype for '''callback''' is: {{{#!highlight cpp callback syntax }}} . where its parameters are: ||`callback parameter`||description|| . optional return value info... . optional remarks or details...
- to display
The function prototype for callback is:
callback syntax
- where its parameters are:
callback parameter
description
- optional return value info...
- optional remarks or details...
Remarks Section Formatting Details |
|
Location |
Action: Generally the Remarks section is roughly organized in the same order as the function parameters. Callback details should be located accordingly, or at the top of the Remarks section if there isn't much else, but below any fundamental or critical remarks about the main function as a whole, if present. But, logic should prevail in determining where to place this information if the Remarks section is large. The callback information should be prominent. |
Example: SDL_CreateThread(), SDL_AddEventWatch(), SDL_SetAssertionHandler() |
|
Alignment |
Action: As shown in the basic format above, only the first line should be left-justified. Everything else related directly to the callback should be indented one level (or more) to indicate it's relationship to the callback as opposed to the main function. |
If the callback parameter is not callback |
Action: Replace callback in the basic format above with the function parameter name used in the main function to refer to the callback function. |
Example: SDL_SetEventFilter(), SDL_CreateThread(), SDL_SetAssertionHandler() |
|
For "callback syntax" in the basic format above |
Action: Replace "callback syntax" with the callback function's syntax formatted the same as the main function's syntax. (See Syntax above for details.) |
If the callback function name requires any explanation |
Action: Replace "where its parameters are:" in the basic format above with the following: |
Example: SDL_AddEventWatch() |
|
For | callback parameter | description | in the basic format above |
Action 1: Duplicate the line from above for each parameter in the callback (ie: there should be 2 lines for 2 parameters). |
Action 2: Replace "callback parameter" with the name of each callback function parameter using the same formatting instructions as the main function except use `monospace` (surrounding backticks) rather than bold to highlight the parameter names in the first column. |
|
Action 3: Replace "description" with an appropriate description of the callback's parameter. See the following for specific parameters. |
|
Example: SDL_FilterEvents(), SDL_LogSetOutputFunction() |
|
For the userdata parameter (or comparable) |
Action: Use the following text (modified as necessary): |
Example: SDL_AddEventWatch(), SDL_AddTimer() |
|
If the callback function's return value is important |
Action 1: Replace "optional return value info..." in the basic format above with the relevant return value information. Be sure to indent text one level as shown. |
Note: Callback return value information may be omitted if it is not important. |
|
Example: SDL_AddEventWatch(), SDL_AddTimer() |
|
If there are "optional remarks or details" |
Action: Replace "optional remarks or details..." in the basic format above with any other relevant information about the callback function. Be sure to indent text at least one level as shown. |
Example: SDL_LogGetOutputFunction(), SDL_LogSetOutputFunction() |
Resources
Our goal is to create accurate, consistent, helpful, user-friendly documentation. We appreciate your efforts to make your additions fit into the existing framework and retain the same look and feel as much as possible.
If you have questions that aren't addressed here:
- Search for another page that contains something similar to what you want to do and copy all the basics as much as applicable.
Check the other SDL Style Guides.
Post a question to Feedback and include a way to contact you.
Post a question to the Mailing List.
Send a comment or question to <ANTI SPAM wiki AT libsdl DOT org> for clarification.
If you have suggestions for changes or additions to this document or any other portion of the wiki please don't hesitate to contact us with your thoughts. We are happy to have the participation!
Disclaimer
All content modifications are subject to review for consistency and quality. We reserve the right to remove or modify any content added to this wiki at any time. You may direct questions or concerns to <ANTI SPAM wiki AT libsdl DOT org>.
This section has been left in for future reference if a compat section or similar is ever added back. It does not currently apply to any pages.
Compatibility Functions
Compatibility functions are present in the API for backward compatibility only and thus are treated slightly differently than functions from the current version. Use the following formatting specifics in addition to those listed above for all CategoryCompat pages::
Action 1: The top of every compatibility function page should include the following, verbatim, to be placed below the pragma markup, below red
if present, and above the page title:
Action 2:
If only one SDL 1.3 function replaces the compatibility function
Action: See Markup A below.
Example: ]](), [[()
If more than one SDL 1.3 function has replaced the compatibility function
Action: See Markup B below.
Note: Listing more than two replacement functions should occur only rarely, if at all. Please avoid making this list any larger than necessary. This is NOT a related functions list!
Example: SDL_AudioDriverName(), SDL_WM_ToggleFullScreen()
If there are no equivalent functions in SDL 1.3
Action: See Markup C below.
Example: SDL_Flip(), [[]]()
Markup A: Add the following section to the end of the page above the footer. Replace SDL_Function with the name of the appropriate SDL 1.3 function:
Example: ]](), [[()
Markup B: Add the following section to the end of the page above the footer. Create a list of functions by repeating the [[SDL_Function]] markup, separating each member of the list with a comma, and placing the most direct counterpart first, alphabetizing any additional functions after that.
Example: SDL_WM_ToggleFullscreen(), SDL_WM_GrabInput()
Markup C: Add the following section to the end of the page above the footer. Replace Other options here with text describing other options in SDL 1.3 that could be used to accomplish the same goal, or remove it if there is no applicable text:
Example: SDL_EnableKeyRepeat() (see other CategoryCompat pages for more examples)