|
Size: 11541
Comment: update content (in progress)
|
Size: 13769
Comment: update content (in progress)
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 177: | Line 177: |
| The Return Value section provides basic information about what, if anything, a function will return. Most return values follow one of these 2 basic formats, depending upon whether a call to [[SDL_GetError]]() is relevant: {{{ Returns <something> on success or <something else> on failure. }}} ''or'' {{{ 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 applicable standard statement or when some other action is required. ||||<bgcolor="#EDEDED">''How to use the Options table''|| ||<( |2 30%>''If'' a __simple replacement__ is all that is required||''Action'' will only contain two replacement statements with the top being for success (`<something>`) and the bottom being for failure (`<something else>`).|| ||''Example'': If the second column says<<BR>>''Action'': `0`<<BR>>`a negative error code`<<BR>>then `<something>` should be replaced with the number `0` and `<something else>` should be replaced by the phrase `a negative error code`.|| ||<( 30%>''If'' a __complex replacement or other action__ is required||''Action'' will detail what to do instead.|| ||||<bgcolor="#EDEDED">''Options''|| ||<( 30%>''If'' the return value is __0 or < 0__||''Action'': `0`<<BR>>`a negative error code`|| ||<( 30%>''If'' the return value is __an int other than above__||''Action'': Replace `<something>` and `<something else>` with the applicable integers.|| ||<( 30%>''If'' the return value is __boolean__||''Action'':`SDL_TRUE`<<BR>>`SDL_FALSE`|| ||<( |2 30%>''If'' the return value is __a structure__||''Action'': Ideally, you would search for other functions using the same return value and replicate the formatting. If this is not possible the general format will approximate: `a/an/the [[SDL_StructureName]] representing...` for success. Failure statement will depend upon what it is. See other ''If''s for options.|| ||''Example'': [[SDL_CreateRGBSurfaceFrom]]()|| ||<( |2 30%>''If'' the return value is __void__||''Action'': Delete the entire Return Value section, including the header.|| ||''Example'': [[SDL_FreeSurface]]()|| |
DRAFT |
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.
Contents
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 accurate, 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.
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>.
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.
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>.
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
}}}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 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 table below for details.
Markup: Use basic table markup and enclose each parameter name in bold markup.
Example: SDL_SetColorKey()
Content-dependent formatting |
|
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 the next If statement in this table for more information. |
|
If a more detailed description is required to adequately explain a parameter |
Action 1 : Appended the following, verbatim, to the end of the brief description |
Action 2: Place the more detailed information in the Remarks section |
|
Action 3: See the next If in this table |
|
If the Remarks section is large |
Action 1: Create an anchor immediately before the additional comments you are adding to the Remarks section |
Action 2: Modify the Remarks link in the parameter description (see Action 2 above) to the following: |
|
Markup: Use <<Anchor(anchorname)>> to create the anchor in the Remarks section. See Anchors for details. |
|
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 |
Action: Use the phrase "filled in with" in the description |
Example: SDL_QueryTexturePixels() |
|
If the description mentions a structure that has a page |
Action: Use the following pattern to describe the parameter: |
Note: Be sure to hyperlink the structure name as shown. |
|
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 == 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 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. |
|
If the description is referring to a specific item from a group (ie: a 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. |
|
Return Value
The Return Value section provides basic information about what, if anything, a function will return.
Most return values follow one of these 2 basic formats, depending upon whether a call to SDL_GetError() is relevant:
Returns <something> on success or <something else> on failure.
or
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 applicable standard statement or when some other action is required.
How to use the Options table |
|
If a simple replacement is all that is required |
Action will only contain two replacement statements with the top being for success (<something>) and the bottom being for failure (<something else>). |
Example: If the second column says |
|
If a complex replacement or other action is required |
Action will detail what to do instead. |
Options |
|
If the return value is 0 or < 0 |
Action: 0 |
If the return value is an int other than above |
Action: Replace <something> and <something else> with the applicable integers. |
If the return value is boolean |
Action:SDL_TRUE |
If the return value is a structure |
Action: Ideally, you would search for other functions using the same return value and replicate the formatting. If this is not possible the general format will approximate: a/an/the [[SDL_StructureName]] representing... for success. Failure statement will depend upon what it is. See other Ifs for options. |
Example: SDL_CreateRGBSurfaceFrom() |
|
If the return value is void |
Action: Delete the entire Return Value section, including the header. |
Example: SDL_FreeSurface() |
|
Code Examples
Remarks
Related Functions
Footer
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>.
