Style Guide: Function Pages

This guide provides specific instructions for editing or adding your own content to each section of the Function pages in this wiki.

General Guidelines

Function pages should provide basic information about the SDL functions to allow users to most effectively utilize them in their projects.

Please observe the following:

• Do not post anything that you do not have permission to post publicly.
• Sections other than Code Examples and Remarks should have adequate details to make them clear and useful while remaining brief wherever possible. Code Examples and Remarks may be more extensive, as necessary.
• Please remember to keep it simple and easy to understand.
• Do not remove, modify, or add section headings unless specifically mentioned below.

For assistance with editing, saving, or wiki-appropriate markup see the Wiki Basics Style Guide.

Return to Table of Contents

Editing Specific Sections

Title

Do not edit the Title.

The Title section consists of the page heading = SDL_FunctionName = and should match the address of the page and the function described on the page.

If you believe a change is necessary please contact us at <ANTI SPAM wiki AT libsdl DOT org>.

Return to Table of Contents

Description

The Description section does not have a heading but immediately follows the page title.

All function descriptions begin with:

• Use this function to

• followed by a clear and concise description of what the function does.

Note: Information presented in this section is limited. Extended description information for more complicated functions should be placed in the Remarks section instead.

red

Do not create a link to the Remarks section in the description if additional information is located there.

Note: As always, if another API page is referenced in the description be sure to hyperlink it and use () outside the link markup if it is a function.

Return to Table of Contents

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 contact us at <ANTI SPAM wiki AT libsdl DOT org>.

Return to Table of Contents

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

• A space between returnType and SDL_FunctionName

• Commas at the end of each line if there is more than 1 param

Note: Do not remove or alter the code box markup surrounding the function syntax.

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
}}}

Return to Table of Contents

Function Parameters

The Function Parameters section provides basic information about each parameter in the function and is presented in table format.

The basic format is as follows:

||'''parameter1'''||description||
||'''parameter2'''||description||
||'''parameterN'''||description||

• The first column contains all of the parameter names, without types, in bold.

• The second column contains a simple description of each parameter.

  • 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 table below for details.

Markup: Use basic table markup and enclose each parameter name in bold markup.

Example: SDL_SetColorKey()

Return to Table of Contents

Return Value

Return to Table of Contents

Code Examples

Return to Table of Contents

Remarks

Return to Table of Contents

Related Functions

Return to Table of Contents

Footer

Return to Table of Contents

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:

1. Search for another page that contains something similar to what you want to do and copy all the basics as much as applicable.

2. Check the other SDL Style Guides.

3. Post a question to Feedback and

include a way to contact you.

1. Post a question to the Mailing List

2. 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