(svn r9662) -Documentation: Doxygen corrections and @file omissions

pull/155/head
belugas 17 years ago
parent 37743094ec
commit 097b3b3c7b

@ -249,6 +249,7 @@ void EnginesDailyLoop()
/** Accept an engine prototype. XXX - it is possible that the top-player /** Accept an engine prototype. XXX - it is possible that the top-player
* changes while you are waiting to accept the offer? Then it becomes invalid * changes while you are waiting to accept the offer? Then it becomes invalid
* @param tile unused * @param tile unused
* @param flags operation to perfom
* @param p1 engine-prototype offered * @param p1 engine-prototype offered
* @param p2 unused * @param p2 unused
*/ */
@ -350,6 +351,7 @@ void EnginesMonthlyLoop()
/** Rename an engine. /** Rename an engine.
* @param tile unused * @param tile unused
* @param flags operation to perfom
* @param p1 engine ID to rename * @param p1 engine ID to rename
* @param p2 unused * @param p2 unused
*/ */

@ -295,7 +295,7 @@ typedef EngineRenew* EngineRenewList;
/** /**
* Remove all engine replacement settings for the player. * Remove all engine replacement settings for the player.
* @param er The renewlist for a given player. * @param erl The renewlist for a given player.
* @return The new renewlist for the player. * @return The new renewlist for the player.
*/ */
void RemoveAllEngineReplacement(EngineRenewList* erl); void RemoveAllEngineReplacement(EngineRenewList* erl);

@ -57,7 +57,7 @@ FiosItem *FiosAlloc()
/** /**
* Compare two FiosItem's. Used with qsort when sorting the file list. * Compare two FiosItem's. Used with qsort when sorting the file list.
* @param a A pointer to the first FiosItem to compare. * @param a A pointer to the first FiosItem to compare.
* @param a A pointer to the second FiosItem to compare. * @param b A pointer to the second FiosItem to compare.
* @return -1, 0 or 1, depending on how the two items should be sorted. * @return -1, 0 or 1, depending on how the two items should be sorted.
*/ */
int CDECL compare_FiosItems(const void *a, const void *b) int CDECL compare_FiosItems(const void *a, const void *b)
@ -200,9 +200,8 @@ bool FileExists(const char *filename)
typedef byte fios_getlist_callback_proc(int mode, const char *filename, const char *ext, char *title); typedef byte fios_getlist_callback_proc(int mode, const char *filename, const char *ext, char *title);
/** Create a list of the files in a directory, according to some arbitrary rule. /** Create a list of the files in a directory, according to some arbitrary rule.
* @param num Will be filled with the amount of items.
* @param mode The mode we are in. Some modes don't allow 'parent'. * @param mode The mode we are in. Some modes don't allow 'parent'.
* @param callback The function that is called where you need to do the filtering. * @param callback_proc The function that is called where you need to do the filtering.
* @return Return the list of files. */ * @return Return the list of files. */
static FiosItem *FiosGetFileList(int mode, fios_getlist_callback_proc *callback_proc) static FiosItem *FiosGetFileList(int mode, fios_getlist_callback_proc *callback_proc)
{ {

@ -899,7 +899,7 @@ static void _SetGeneratingWorldProgress(gwp_class cls, uint progress, uint total
/** /**
* Set the total of a stage of the world generation. * Set the total of a stage of the world generation.
* @param class the current class we are in. * @param cls the current class we are in.
* @param total Set the total expected items for this class. * @param total Set the total expected items for this class.
* *
* Warning: this function isn't clever. Don't go from class 4 to 3. Go upwards, always. * Warning: this function isn't clever. Don't go from class 4 to 3. Go upwards, always.
@ -914,7 +914,7 @@ void SetGeneratingWorldProgress(gwp_class cls, uint total)
/** /**
* Increases the current stage of the world generation with one. * Increases the current stage of the world generation with one.
* @param class the current class we are in. * @param cls the current class we are in.
* *
* Warning: this function isn't clever. Don't go from class 4 to 3. Go upwards, always. * Warning: this function isn't clever. Don't go from class 4 to 3. Go upwards, always.
* Also, progress works if total is zero, total works if progress is zero. * Also, progress works if total is zero, total works if progress is zero.

@ -275,7 +275,7 @@ void GfxDrawLine(int x, int y, int x2, int y2, int color)
/** Truncate a given string to a maximum width if neccessary. /** Truncate a given string to a maximum width if neccessary.
* If the string is truncated, add three dots ('...') to show this. * If the string is truncated, add three dots ('...') to show this.
* @param *dest string that is checked and possibly truncated * @param *str string that is checked and possibly truncated
* @param maxw maximum width in pixels of the string * @param maxw maximum width in pixels of the string
* @return new width of (truncated) string */ * @return new width of (truncated) string */
static int TruncateString(char *str, int maxw) static int TruncateString(char *str, int maxw)
@ -413,11 +413,11 @@ void DrawStringCenterUnderlineTruncated(int xl, int xr, int y, StringID str, uin
/** 'Correct' a string to a maximum length. Longer strings will be cut into /** 'Correct' a string to a maximum length. Longer strings will be cut into
* additional lines at whitespace characters if possible. The string parameter * additional lines at whitespace characters if possible. The string parameter
* is modified with terminating characters mid-string which are the * is modified with terminating characters mid-string which are the
* placeholders for the newlines.<br/> * placeholders for the newlines.
* The string WILL be truncated if there was no whitespace for the current * The string WILL be truncated if there was no whitespace for the current
* line's maximum width. * line's maximum width.
* *
* @note To know if the the terminating '\0' is the string end or just a * @note To know if the terminating '\0' is the string end or just a
* newline, the returned 'num' value should be consulted. The num'th '\0', * newline, the returned 'num' value should be consulted. The num'th '\0',
* starting with index 0 is the real string end. * starting with index 0 is the real string end.
* *
@ -487,7 +487,7 @@ end_of_inner_loop:
* @param x Centre the string around this pixel width * @param x Centre the string around this pixel width
* @param y Draw the string at this pixel height (first line's bottom) * @param y Draw the string at this pixel height (first line's bottom)
* @param str String to draw * @param str String to draw
* @param max Maximum width the string can have before it is wrapped */ * @param maxw Maximum width the string can have before it is wrapped */
void DrawStringMultiCenter(int x, int y, StringID str, int maxw) void DrawStringMultiCenter(int x, int y, StringID str, int maxw)
{ {
char buffer[512]; char buffer[512];
@ -626,7 +626,7 @@ BoundingRect GetStringBoundingBox(const char *str)
/** Draw a string at the given coordinates with the given colour /** Draw a string at the given coordinates with the given colour
* @param string the string to draw * @param string the string to draw
* @param x offset from left side of the screen, if negative offset from the right side * @param x offset from left side of the screen, if negative offset from the right side
* @param x offset from top side of the screen, if negative offset from the bottom * @param y offset from top side of the screen, if negative offset from the bottom
* @param real_color colour of the string, see _string_colormap in * @param real_color colour of the string, see _string_colormap in
* table/palettes.h or docs/ottd-colourtext-palette.png * table/palettes.h or docs/ottd-colourtext-palette.png
* @return the x-coordinates where the drawing has finished. If nothing is drawn * @return the x-coordinates where the drawing has finished. If nothing is drawn

@ -44,7 +44,7 @@ uint EngList_Count(const EngineList *el)
/** Add new item at the end of Engine List /** Add new item at the end of Engine List
* @param el list o which to add an engine * @param el list o which to add an engine
* @param eif engine to add to the list * @param eid engine to add to the list
*/ */
void EngList_Add(EngineList *el, EngineID eid) void EngList_Add(EngineList *el, EngineID eid)
{ {
@ -81,7 +81,7 @@ void EngList_Sort(EngineList *el, EngList_SortTypeFunction compare)
* @param el list to be sorted * @param el list to be sorted
* @param compare function for evaluation of the quicksort * @param compare function for evaluation of the quicksort
* @param begin start of sorting * @param begin start of sorting
* @param count of items to be sorted * @param num_items count of items to be sorted
*/ */
void EngList_SortPartial(EngineList *el, EngList_SortTypeFunction compare, uint begin, uint num_items) void EngList_SortPartial(EngineList *el, EngList_SortTypeFunction compare, uint begin, uint num_items)
{ {

@ -1247,7 +1247,8 @@ static OnButtonClick * const _editor_terraform_button_proc[] = {
/** Callback function for the scenario editor 'reset landscape' confirmation window /** Callback function for the scenario editor 'reset landscape' confirmation window
* @param yes_clicked boolean value, true when yes was clicked, false otherwise */ * @param w Window unused
* @param confirmed boolean value, true when yes was clicked, false otherwise */
static void ResetLandscapeConfirmationCallback(Window *w, bool confirmed) static void ResetLandscapeConfirmationCallback(Window *w, bool confirmed)
{ {
if (confirmed) { if (confirmed) {

@ -1,5 +1,7 @@
/* $Id$ */ /* $Id$ */
/** @file array.hpp */
#ifndef ARRAY_HPP #ifndef ARRAY_HPP
#define ARRAY_HPP #define ARRAY_HPP

@ -1,5 +1,7 @@
/* $Id$ */ /* $Id$ */
/** @file autocopyptr.hpp */
#ifndef AUTOCOPYPTR_HPP #ifndef AUTOCOPYPTR_HPP
#define AUTOCOPYPTR_HPP #define AUTOCOPYPTR_HPP

@ -1,5 +1,7 @@
/* $Id$ */ /* $Id$ */
/** @file autoptr.hpp */
#ifndef AUTOPTR_HPP #ifndef AUTOPTR_HPP
#define AUTOPTR_HPP #define AUTOPTR_HPP

@ -1,5 +1,7 @@
/* $Id$ */ /* $Id$ */
/** @file binaryheap.hpp */
#ifndef BINARYHEAP_HPP #ifndef BINARYHEAP_HPP
#define BINARYHEAP_HPP #define BINARYHEAP_HPP

@ -1,5 +1,7 @@
/* $Id$ */ /* $Id$ */
/** @file blob.hpp */
#ifndef BLOB_HPP #ifndef BLOB_HPP
#define BLOB_HPP #define BLOB_HPP

@ -1,5 +1,7 @@
/* $Id$ */ /* $Id$ */
/** @file countedptr.hpp */
#ifndef COUNTEDPTR_HPP #ifndef COUNTEDPTR_HPP
#define COUNTEDPTR_HPP #define COUNTEDPTR_HPP

@ -1,5 +1,7 @@
/* $Id$ */ /* $Id$ */
/** @file crc32.hpp */
#ifndef CRC32_HPP #ifndef CRC32_HPP
#define CRC32_HPP #define CRC32_HPP

@ -1,5 +1,7 @@
/* $Id$ */ /* $Id$ */
/** @file fixedsizearray.hpp */
#ifndef FIXEDSIZEARRAY_HPP #ifndef FIXEDSIZEARRAY_HPP
#define FIXEDSIZEARRAY_HPP #define FIXEDSIZEARRAY_HPP

@ -1,5 +1,7 @@
/* $Id$ */ /* $Id$ */
/** @file hashtable.hpp */
#ifndef HASHTABLE_HPP #ifndef HASHTABLE_HPP
#define HASHTABLE_HPP #define HASHTABLE_HPP
@ -97,7 +99,7 @@ struct CHashTableSlotT
} }
}; };
/** @class CHashTableT<Titem, Thash_bits> - simple hash table /** class CHashTableT<Titem, Thash_bits> - simple hash table
* of pointers allocated elsewhere. * of pointers allocated elsewhere.
* *
* Supports: Add/Find/Remove of Titems. * Supports: Add/Find/Remove of Titems.

@ -38,6 +38,7 @@ int32 CmdSetPlayerFace(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
/** Change the player's company-colour /** Change the player's company-colour
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 bitstuffed: * @param p1 bitstuffed:
* p1 bits 0-7 scheme to set * p1 bits 0-7 scheme to set
* p1 bits 8-9 set in use state or first/second colour * p1 bits 8-9 set in use state or first/second colour
@ -117,6 +118,7 @@ int32 CmdSetPlayerColor(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
/** Increase the loan of your company. /** Increase the loan of your company.
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 unused * @param p1 unused
* @param p2 when set, loans the maximum amount in one go (press CTRL) * @param p2 when set, loans the maximum amount in one go (press CTRL)
*/ */
@ -146,6 +148,7 @@ int32 CmdIncreaseLoan(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
/** Decrease the loan of your company. /** Decrease the loan of your company.
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 unused * @param p1 unused
* @param p2 when set, pays back the maximum loan permitting money (press CTRL) * @param p2 when set, pays back the maximum loan permitting money (press CTRL)
*/ */
@ -186,6 +189,7 @@ int32 CmdDecreaseLoan(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
/** Change the name of the company. /** Change the name of the company.
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 unused * @param p1 unused
* @param p2 unused * @param p2 unused
*/ */
@ -213,6 +217,7 @@ int32 CmdChangeCompanyName(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
/** Change the name of the president. /** Change the name of the president.
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 unused * @param p1 unused
* @param p2 unused * @param p2 unused
*/ */
@ -251,6 +256,7 @@ int32 CmdChangePresidentName(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
* the game is unpaused. A counter is used instead of a boolean value * the game is unpaused. A counter is used instead of a boolean value
* to have more control over the game when saving/loading, etc. * to have more control over the game when saving/loading, etc.
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 0 = decrease pause counter; 1 = increase pause counter * @param p1 0 = decrease pause counter; 1 = increase pause counter
* @param p2 unused * @param p2 unused
*/ */
@ -269,6 +275,7 @@ int32 CmdPause(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
* This is normally only enabled in offline mode, but if there is a debug * This is normally only enabled in offline mode, but if there is a debug
* build, you can cheat (to test). * build, you can cheat (to test).
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 the amount of money to receive (if negative), or spend (if positive) * @param p1 the amount of money to receive (if negative), or spend (if positive)
* @param p2 unused * @param p2 unused
*/ */
@ -286,6 +293,7 @@ int32 CmdMoneyCheat(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
* players if you have paid off your loan (either explicitely, or implicitely * players if you have paid off your loan (either explicitely, or implicitely
* given the fact that you have more money than loan). * given the fact that you have more money than loan).
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 the amount of money to transfer; max 20.000.000 * @param p1 the amount of money to transfer; max 20.000.000
* @param p2 the player to transfer the money to * @param p2 the player to transfer the money to
*/ */
@ -317,6 +325,7 @@ int32 CmdGiveMoney(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
* in file 'settings_gui.c' _game_setting_info[]; we'll just trust the server it knows * in file 'settings_gui.c' _game_setting_info[]; we'll just trust the server it knows
* what to do and does this correctly * what to do and does this correctly
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 the difficulty setting being changed. If it is -1, the difficulty level * @param p1 the difficulty setting being changed. If it is -1, the difficulty level
* itself is changed. The new value is inside p2 * itself is changed. The new value is inside p2
* @param p2 new value for a difficulty setting or difficulty level * @param p2 new value for a difficulty setting or difficulty level

@ -677,9 +677,10 @@ static void TooltipsWndProc(Window *w, WindowEvent *e)
} }
/** Shows a tooltip /** Shows a tooltip
* @param str String to be displayed * @param str String to be displayed
* @param params (optional) up to 5 pieces of additional information that may be * @param paramcount number of params to deal with
* added to a tooltip; currently only supports parameters of {NUM} (integer) */ * @param params (optional) up to 5 pieces of additional information that may be
* added to a tooltip; currently only supports parameters of {NUM} (integer) */
void GuiShowTooltipsWithArgs(StringID str, uint paramcount, const uint32 params[]) void GuiShowTooltipsWithArgs(StringID str, uint paramcount, const uint32 params[])
{ {
char buffer[512]; char buffer[512];
@ -824,8 +825,8 @@ static void DelChar(Textbuf *tb, bool backspace)
/** /**
* Delete a character from a textbuffer, either with 'Delete' or 'Backspace' * Delete a character from a textbuffer, either with 'Delete' or 'Backspace'
* The character is delete from the position the caret is at * The character is delete from the position the caret is at
* @param tb @Textbuf type to be changed * @param tb Textbuf type to be changed
* @param delmode Type of deletion, either @WKC_BACKSPACE or @WKC_DELETE * @param delmode Type of deletion, either WKC_BACKSPACE or WKC_DELETE
* @return Return true on successfull change of Textbuf, or false otherwise * @return Return true on successfull change of Textbuf, or false otherwise
*/ */
bool DeleteTextBufferChar(Textbuf *tb, int delmode) bool DeleteTextBufferChar(Textbuf *tb, int delmode)
@ -843,7 +844,7 @@ bool DeleteTextBufferChar(Textbuf *tb, int delmode)
/** /**
* Delete every character in the textbuffer * Delete every character in the textbuffer
* @param tb @Textbuf buffer to be emptied * @param tb Textbuf buffer to be emptied
*/ */
void DeleteTextBufferAll(Textbuf *tb) void DeleteTextBufferAll(Textbuf *tb)
{ {
@ -856,7 +857,7 @@ void DeleteTextBufferAll(Textbuf *tb)
* Insert a character to a textbuffer. If maxwidth of the Textbuf is zero, * Insert a character to a textbuffer. If maxwidth of the Textbuf is zero,
* we don't care about the visual-length but only about the physical * we don't care about the visual-length but only about the physical
* length of the string * length of the string
* @param tb @Textbuf type to be changed * @param tb Textbuf type to be changed
* @param key Character to be inserted * @param key Character to be inserted
* @return Return true on successfull change of Textbuf, or false otherwise * @return Return true on successfull change of Textbuf, or false otherwise
*/ */
@ -880,8 +881,8 @@ bool InsertTextBufferChar(Textbuf *tb, WChar key)
/** /**
* Handle text navigation with arrow keys left/right. * Handle text navigation with arrow keys left/right.
* This defines where the caret will blink and the next characer interaction will occur * This defines where the caret will blink and the next characer interaction will occur
* @param tb @Textbuf type where navigation occurs * @param tb Textbuf type where navigation occurs
* @param navmode Direction in which navigation occurs @WKC_LEFT, @WKC_RIGHT, @WKC_END, @WKC_HOME * @param navmode Direction in which navigation occurs WKC_LEFT, WKC_RIGHT, WKC_END, WKC_HOME
* @return Return true on successfull change of Textbuf, or false otherwise * @return Return true on successfull change of Textbuf, or false otherwise
*/ */
bool MoveTextBufferPos(Textbuf *tb, int navmode) bool MoveTextBufferPos(Textbuf *tb, int navmode)
@ -924,7 +925,7 @@ bool MoveTextBufferPos(Textbuf *tb, int navmode)
/** /**
* Initialize the textbuffer by supplying it the buffer to write into * Initialize the textbuffer by supplying it the buffer to write into
* and the maximum length of this buffer * and the maximum length of this buffer
* @param tb @Textbuf type which is getting initialized * @param tb Textbuf type which is getting initialized
* @param buf the buffer that will be holding the data for input * @param buf the buffer that will be holding the data for input
* @param maxlength maximum length in characters of this buffer * @param maxlength maximum length in characters of this buffer
* @param maxwidth maximum length in pixels of this buffer. If reached, buffer * @param maxwidth maximum length in pixels of this buffer. If reached, buffer
@ -940,10 +941,10 @@ void InitializeTextBuffer(Textbuf *tb, const char *buf, uint16 maxlength, uint16
} }
/** /**
* Update @Textbuf type with its actual physical character and screenlength * Update Textbuf type with its actual physical character and screenlength
* Get the count of characters in the string as well as the width in pixels. * Get the count of characters in the string as well as the width in pixels.
* Useful when copying in a larger amount of text at once * Useful when copying in a larger amount of text at once
* @param tb @Textbuf type which length is calculated * @param tb Textbuf type which length is calculated
*/ */
void UpdateTextBufferSize(Textbuf *tb) void UpdateTextBufferSize(Textbuf *tb)
{ {
@ -1271,8 +1272,7 @@ static const WindowDesc _query_desc = {
* @param message string that will be shown for the window * @param message string that will be shown for the window
* @param parent pointer to parent window, if this pointer is NULL the parent becomes * @param parent pointer to parent window, if this pointer is NULL the parent becomes
* the main window WC_MAIN_WINDOW * the main window WC_MAIN_WINDOW
* @param x,y coordinates to show the window at * @param callback callback function pointer to set in the window descriptor*/
* @param yes_no_callback callback function called when window is closed through any button */
void ShowQuery(StringID caption, StringID message, Window *parent, void (*callback)(Window*, bool)) void ShowQuery(StringID caption, StringID message, Window *parent, void (*callback)(Window*, bool))
{ {
Window *w = AllocateWindowDesc(&_query_desc); Window *w = AllocateWindowDesc(&_query_desc);
@ -1722,6 +1722,7 @@ static int32 ClickChangePlayerCheat(int32 p1, int32 p2)
/** /**
* @param p1 -1 or +1 (down/up) * @param p1 -1 or +1 (down/up)
* @param p2 unused
*/ */
static int32 ClickChangeClimateCheat(int32 p1, int32 p2) static int32 ClickChangeClimateCheat(int32 p1, int32 p2)
{ {
@ -1735,6 +1736,7 @@ static int32 ClickChangeClimateCheat(int32 p1, int32 p2)
extern void EnginesMonthlyLoop(); extern void EnginesMonthlyLoop();
/** /**
* @param p1 unused
* @param p2 1 (increase) or -1 (decrease) * @param p2 1 (increase) or -1 (decrease)
*/ */
static int32 ClickChangeDateCheat(int32 p1, int32 p2) static int32 ClickChangeDateCheat(int32 p1, int32 p2)

@ -1,5 +1,7 @@
/* $Id$ */ /* $Id$ */
/** @file bemidi.cpp */
#include "../stdafx.h" #include "../stdafx.h"
#include "../openttd.h" #include "../openttd.h"
#include "bemidi.h" #include "bemidi.h"

@ -1,5 +1,7 @@
/* $Id$ */ /* $Id$ */
/** @file dmusic.cpp */
#ifdef WIN32_ENABLE_DIRECTMUSIC_SUPPORT #ifdef WIN32_ENABLE_DIRECTMUSIC_SUPPORT
#include "../stdafx.h" #include "../stdafx.h"
@ -14,13 +16,13 @@
#include <dmusicf.h> #include <dmusicf.h>
// the performance object controls manipulation of the segments /** the performance object controls manipulation of the segments */
static IDirectMusicPerformance* performance = NULL; static IDirectMusicPerformance* performance = NULL;
// the loader object can load many types of DMusic related files /** the loader object can load many types of DMusic related files */
static IDirectMusicLoader* loader = NULL; static IDirectMusicLoader* loader = NULL;
// the segment object is where the MIDI data is stored for playback /** the segment object is where the MIDI data is stored for playback */
static IDirectMusicSegment* segment = NULL; static IDirectMusicSegment* segment = NULL;
static bool seeking = false; static bool seeking = false;
@ -54,12 +56,12 @@ static const char* DMusicMidiStart(const char* const* parm)
return "ole32.dll load failed"; return "ole32.dll load failed";
} }
// Initialize COM /* Initialize COM */
if (FAILED(proc.CoInitialize(NULL))) { if (FAILED(proc.CoInitialize(NULL))) {
return "COM initialization failed"; return "COM initialization failed";
} }
// create the performance object /* create the performance object */
if (FAILED(proc.CoCreateInstance( if (FAILED(proc.CoCreateInstance(
CLSID_DirectMusicPerformance, CLSID_DirectMusicPerformance,
NULL, NULL,
@ -71,7 +73,7 @@ static const char* DMusicMidiStart(const char* const* parm)
return "Failed to create the performance object"; return "Failed to create the performance object";
} }
// initialize it /* initialize it */
if (FAILED(performance->Init(NULL, NULL, NULL))) { if (FAILED(performance->Init(NULL, NULL, NULL))) {
performance->Release(); performance->Release();
performance = NULL; performance = NULL;
@ -79,7 +81,7 @@ static const char* DMusicMidiStart(const char* const* parm)
return "Failed to initialize performance object"; return "Failed to initialize performance object";
} }
// choose default Windows synth /* choose default Windows synth */
if (FAILED(performance->AddPort(NULL))) { if (FAILED(performance->AddPort(NULL))) {
performance->CloseDown(); performance->CloseDown();
performance->Release(); performance->Release();
@ -88,7 +90,7 @@ static const char* DMusicMidiStart(const char* const* parm)
return "AddPort failed"; return "AddPort failed";
} }
// create the loader object; this will be used to load the MIDI file /* create the loader object; this will be used to load the MIDI file */
if (FAILED(proc.CoCreateInstance( if (FAILED(proc.CoCreateInstance(
CLSID_DirectMusicLoader, CLSID_DirectMusicLoader,
NULL, NULL,
@ -136,7 +138,7 @@ static void DMusicMidiStop()
static void DMusicMidiPlaySong(const char* filename) static void DMusicMidiPlaySong(const char* filename)
{ {
// set up the loader object info /* set up the loader object info */
DMUS_OBJECTDESC obj_desc; DMUS_OBJECTDESC obj_desc;
ZeroMemory(&obj_desc, sizeof(obj_desc)); ZeroMemory(&obj_desc, sizeof(obj_desc));
obj_desc.dwSize = sizeof(obj_desc); obj_desc.dwSize = sizeof(obj_desc);
@ -148,13 +150,13 @@ static void DMusicMidiPlaySong(const char* filename)
obj_desc.wszFileName, lengthof(obj_desc.wszFileName) obj_desc.wszFileName, lengthof(obj_desc.wszFileName)
); );
// release the existing segment if we have any /* release the existing segment if we have any */
if (segment != NULL) { if (segment != NULL) {
segment->Release(); segment->Release();
segment = NULL; segment = NULL;
} }
// make a new segment /* make a new segment */
if (FAILED(loader->GetObject( if (FAILED(loader->GetObject(
&obj_desc, IID_IDirectMusicSegment, (LPVOID*)&segment &obj_desc, IID_IDirectMusicSegment, (LPVOID*)&segment
))) { ))) {
@ -162,7 +164,7 @@ static void DMusicMidiPlaySong(const char* filename)
return; return;
} }
// tell the segment what kind of data it contains /* tell the segment what kind of data it contains */
if (FAILED(segment->SetParam( if (FAILED(segment->SetParam(
GUID_StandardMIDIFile, 0xFFFFFFFF, 0, 0, performance GUID_StandardMIDIFile, 0xFFFFFFFF, 0, 0, performance
))) { ))) {
@ -170,13 +172,13 @@ static void DMusicMidiPlaySong(const char* filename)
return; return;
} }
// tell the segment to 'download' the instruments /* tell the segment to 'download' the instruments */
if (FAILED(segment->SetParam(GUID_Download, 0xFFFFFFFF, 0, 0, performance))) { if (FAILED(segment->SetParam(GUID_Download, 0xFFFFFFFF, 0, 0, performance))) {
DEBUG(driver, 0, "DirectMusic: failed to download instruments"); DEBUG(driver, 0, "DirectMusic: failed to download instruments");
return; return;
} }
// start playing the MIDI file /* start playing the MIDI file */
if (FAILED(performance->PlaySegment(segment, 0, 0, NULL))) { if (FAILED(performance->PlaySegment(segment, 0, 0, NULL))) {
DEBUG(driver, 0, "DirectMusic: PlaySegment failed"); DEBUG(driver, 0, "DirectMusic: PlaySegment failed");
return; return;
@ -210,8 +212,7 @@ static bool DMusicMidiIsSongPlaying()
static void DMusicMidiSetVolume(byte vol) static void DMusicMidiSetVolume(byte vol)
{ {
// 0 - 127 -> -2000 - 0 long db = vol * 2000 / 127 - 2000; ///< 0 - 127 -> -2000 - 0
long db = vol * 2000 / 127 - 2000;
performance->SetGlobalParam(GUID_PerfMasterVolume, &db, sizeof(db)); performance->SetGlobalParam(GUID_PerfMasterVolume, &db, sizeof(db));
} }

@ -136,7 +136,7 @@ static uint32 _grm_engines[TOTAL_NUM_ENGINES];
* loading/parsing grf files, not for runtime debug messages as there * loading/parsing grf files, not for runtime debug messages as there
* is no file information available during that time. * is no file information available during that time.
* @param severity debugging severity level, see debug.h * @param severity debugging severity level, see debug.h
* @param debugging message in printf() format */ * @param str message in printf() format */
void CDECL grfmsg(int severity, const char *str, ...) void CDECL grfmsg(int severity, const char *str, ...)
{ {
char buf[1024]; char buf[1024];
@ -234,6 +234,7 @@ static GRFFile *GetFileByFilename(const char *filename)
/** Used when setting an object's property to map to the GRF's strings /** Used when setting an object's property to map to the GRF's strings
* while taking in consideration the "drift" between TTDPatch string system and OpenTTD's one * while taking in consideration the "drift" between TTDPatch string system and OpenTTD's one
* @param grfid Id of the grf file
* @param str StringID that we want to have the equivalent in OoenTTD * @param str StringID that we want to have the equivalent in OoenTTD
* @return the properly adjusted StringID * @return the properly adjusted StringID
*/ */
@ -2004,8 +2005,8 @@ static const SpriteGroup* NewCallBackResultSpriteGroup(uint16 value)
/** /**
* Creates a spritegroup representing a sprite number result. * Creates a spritegroup representing a sprite number result.
* @param value The sprite number. * @param sprite The sprite number.
* @param sprites The number of sprites per set. * @param num_sprites The number of sprites per set.
* @return A spritegroup representing the sprite number result. * @return A spritegroup representing the sprite number result.
*/ */
static const SpriteGroup* NewResultSpriteGroup(SpriteID sprite, byte num_sprites) static const SpriteGroup* NewResultSpriteGroup(SpriteID sprite, byte num_sprites)

@ -187,7 +187,8 @@ void AppendStaticGRFConfigs(GRFConfig **dst)
} }
/** Appends an element to a list of GRFs /** Appends an element to a list of GRFs
* @param dst the head of the list to add to */ * @param dst the head of the list to add to
* @param el the new tail to be */
void AppendToGRFConfigList(GRFConfig **dst, GRFConfig *el) void AppendToGRFConfigList(GRFConfig **dst, GRFConfig *el)
{ {
GRFConfig **tail = dst; GRFConfig **tail = dst;

@ -886,7 +886,7 @@ bool UsesWagonOverride(const Vehicle* v)
* @param param1 First parameter of the callback * @param param1 First parameter of the callback
* @param param2 Second parameter of the callback * @param param2 Second parameter of the callback
* @param engine Engine type of the vehicle to evaluate the callback for * @param engine Engine type of the vehicle to evaluate the callback for
* @param vehicle The vehicle to evaluate the callback for, or NULL if it doesnt exist yet * @param v The vehicle to evaluate the callback for, or NULL if it doesnt exist yet
* @return The value the callback returned, or CALLBACK_FAILED if it failed * @return The value the callback returned, or CALLBACK_FAILED if it failed
*/ */
uint16 GetVehicleCallback(uint16 callback, uint32 param1, uint32 param2, EngineID engine, const Vehicle *v) uint16 GetVehicleCallback(uint16 callback, uint32 param1, uint32 param2, EngineID engine, const Vehicle *v)

@ -61,7 +61,7 @@ void ResetStationClasses()
/** /**
* Allocate a station class for the given class id. * Allocate a station class for the given class id.
* @param classid A 32 bit value identifying the class. * @param cls A 32 bit value identifying the class.
* @return Index into station_classes of allocated class. * @return Index into station_classes of allocated class.
*/ */
StationClassID AllocateStationClass(uint32 cls) StationClassID AllocateStationClass(uint32 cls)
@ -138,7 +138,7 @@ uint GetNumCustomStations(StationClassID sclass)
/** /**
* Tie a station spec to its station class. * Tie a station spec to its station class.
* @param spec The station spec. * @param statspec The station spec.
*/ */
void SetCustomStationSpec(StationSpec *statspec) void SetCustomStationSpec(StationSpec *statspec)
{ {
@ -614,7 +614,7 @@ uint16 GetStationCallback(uint16 callback, uint32 param1, uint32 param2, const S
/** /**
* Allocate a StationSpec to a Station. This is called once per build operation. * Allocate a StationSpec to a Station. This is called once per build operation.
* @param spec StationSpec to allocate. * @param statspec StationSpec to allocate.
* @param st Station to allocate it to. * @param st Station to allocate it to.
* @param exec Whether to actually allocate the spec. * @param exec Whether to actually allocate the spec.
* @return Index within the Station's spec list, or -1 if the allocation failed. * @return Index within the Station's spec list, or -1 if the allocation failed.
@ -695,10 +695,12 @@ void DeallocateSpecFromStation(Station* st, byte specindex)
} }
/** Draw representation of a station tile for GUI purposes. /** Draw representation of a station tile for GUI purposes.
* @param x, y Position of image. * @param x Position x of image.
* @param dir Direction. * @param y Position y of image.
* @param axis Axis.
* @param railtype Rail type. * @param railtype Rail type.
* @param sclass, station Type of station. * @param sclass, station Type of station.
* @param station station ID
* @return True if the tile was drawn (allows for fallback to default graphic) * @return True if the tile was drawn (allows for fallback to default graphic)
*/ */
bool DrawStationTile(int x, int y, RailType railtype, Axis axis, StationClassID sclass, uint station) bool DrawStationTile(int x, int y, RailType railtype, Axis axis, StationClassID sclass, uint station)

@ -418,8 +418,8 @@ char *GetGRFString(char *buff, uint16 stringid, const char* last)
* The array iso_codes will be used to find that match. * The array iso_codes will be used to find that match.
* If not found, it will have to be standard english * If not found, it will have to be standard english
* This function is called after the user changed language, * This function is called after the user changed language,
* from strings.c:ReadLanguagePack * from strings.cpp:ReadLanguagePack
* @param iso code of current selection * @param iso_name iso code of current selection
*/ */
void SetCurrentGrfLangID(const char *iso_name) void SetCurrentGrfLangID(const char *iso_name)
{ {

@ -240,17 +240,17 @@ static inline NewsID decreaseIndex(NewsID i)
* @param flags various control bits that will show various news-types. See macro NEWS_FLAGS() * @param flags various control bits that will show various news-types. See macro NEWS_FLAGS()
* @param data_a news-specific value based on news type * @param data_a news-specific value based on news type
* @param data_b news-specific value based on news type * @param data_b news-specific value based on news type
* @note flags exists of 4 byte-sized extra parameters.<br/> * @note flags exists of 4 byte-sized extra parameters.
* 1. 0 - 7 display_mode, any of the NewsMode enums (NM_)<br/> * 1. 0 - 7 display_mode, any of the NewsMode enums (NM_)
* 2. 8 - 15 news flags, any of the NewsFlags enums (NF_) NF_INCOLOR are set automatically if needed<br/> * 2. 8 - 15 news flags, any of the NewsFlags enums (NF_) NF_INCOLOR are set automatically if needed
* 3. 16 - 23 news category, any of the NewsType enums (NT_)<br/> * 3. 16 - 23 news category, any of the NewsType enums (NT_)
* 4. 24 - 31 news callback function, any of the NewsCallback enums (DNC_)<br/> * 4. 24 - 31 news callback function, any of the NewsCallback enums (DNC_)
* If the display mode is NM_CALLBACK special news is shown and parameter * If the display mode is NM_CALLBACK special news is shown and parameter
* stringid has a special meaning.<br/> * stringid has a special meaning.
* DNC_TRAINAVAIL, DNC_ROADAVAIL, DNC_SHIPAVAIL, DNC_AIRCRAFTAVAIL: StringID is * DNC_TRAINAVAIL, DNC_ROADAVAIL, DNC_SHIPAVAIL, DNC_AIRCRAFTAVAIL: StringID is
* the index of the engine that is shown<br/> * the index of the engine that is shown
* DNC_BANKRUPCY: bytes 0-3 of StringID contains the player that is in trouble, * DNC_BANKRUPCY: bytes 0-3 of StringID contains the player that is in trouble,
* and 4-7 contains what kind of bankrupcy message is shown, NewsBankrupcy enum (NB_)<br/> * and 4-7 contains what kind of bankrupcy message is shown, NewsBankrupcy enum (NB_)
* @see NewsMode * @see NewsMode
* @see NewsFlags * @see NewsFlags
* @see NewsType * @see NewsType

@ -182,6 +182,7 @@ static TileIndex GetOrderLocation(const Order& o)
/** Add an order to the orderlist of a vehicle. /** Add an order to the orderlist of a vehicle.
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 various bitstuffed elements * @param p1 various bitstuffed elements
* - p1 = (bit 0 - 15) - ID of the vehicle * - p1 = (bit 0 - 15) - ID of the vehicle
* - p1 = (bit 16 - 31) - the selected order (if any). If the last order is given, * - p1 = (bit 16 - 31) - the selected order (if any). If the last order is given,
@ -478,6 +479,7 @@ static void RemoveSharedOrderVehicleList(Vehicle *v)
/** Delete an order from the orderlist of a vehicle. /** Delete an order from the orderlist of a vehicle.
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 the ID of the vehicle * @param p1 the ID of the vehicle
* @param p2 the order to delete (max 255) * @param p2 the order to delete (max 255)
*/ */
@ -557,6 +559,7 @@ int32 CmdDeleteOrder(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
/** Goto next order of order-list. /** Goto next order of order-list.
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 The ID of the vehicle which order is skipped * @param p1 The ID of the vehicle which order is skipped
* @param p2 unused * @param p2 unused
*/ */
@ -600,6 +603,7 @@ int32 CmdSkipOrder(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
/** Modify an order in the orderlist of a vehicle. /** Modify an order in the orderlist of a vehicle.
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 various bitstuffed elements * @param p1 various bitstuffed elements
* - p1 = (bit 0 - 15) - ID of the vehicle * - p1 = (bit 0 - 15) - ID of the vehicle
* - p1 = (bit 16 - 31) - the selected order (if any). If the last order is given, * - p1 = (bit 16 - 31) - the selected order (if any). If the last order is given,
@ -680,6 +684,8 @@ int32 CmdModifyOrder(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
} }
/** Clone/share/copy an order-list of an other vehicle. /** Clone/share/copy an order-list of an other vehicle.
* @param tile unused
* @param flags operation to perform
* @param p1 various bitstuffed elements * @param p1 various bitstuffed elements
* - p1 = (bit 0-15) - destination vehicle to clone orders to (p1 & 0xFFFF) * - p1 = (bit 0-15) - destination vehicle to clone orders to (p1 & 0xFFFF)
* - p1 = (bit 16-31) - source vehicle to clone orders from, if any (none for CO_UNSHARE) * - p1 = (bit 16-31) - source vehicle to clone orders from, if any (none for CO_UNSHARE)
@ -812,6 +818,7 @@ int32 CmdCloneOrder(TileIndex tile, uint32 flags, uint32 p1, uint32 p2)
/** Add/remove refit orders from an order /** Add/remove refit orders from an order
* @param tile Not used * @param tile Not used
* @param flags operation to perform
* @param p1 VehicleIndex of the vehicle having the order * @param p1 VehicleIndex of the vehicle having the order
* @param p2 bitmask * @param p2 bitmask
* - bit 0-7 CargoID * - bit 0-7 CargoID
@ -937,6 +944,7 @@ void RestoreVehicleOrders(const Vehicle* v, const BackuppedOrders* bak)
/** Restore the current order-index of a vehicle and sets service-interval. /** Restore the current order-index of a vehicle and sets service-interval.
* @param tile unused * @param tile unused
* @param flags operation to perform
* @param p1 the ID of the vehicle * @param p1 the ID of the vehicle
* @param p2 various bistuffed elements * @param p2 various bistuffed elements
* - p2 = (bit 0-15) - current order-index (p2 & 0xFFFF) * - p2 = (bit 0-15) - current order-index (p2 & 0xFFFF)

@ -1,6 +1,6 @@
/* $Id$ */ /* $Id$ */
/** @file spritechache.cpp */ /** @file spritecache.cpp */
#include "stdafx.h" #include "stdafx.h"
#include "openttd.h" #include "openttd.h"

@ -1,6 +1,6 @@
/* $Id$ */ /* $Id$ */
/** @file stdfax.h */ /** @file stdafx.h */
#ifndef STDAFX_H #ifndef STDAFX_H
#define STDAFX_H #define STDAFX_H

@ -36,17 +36,13 @@ static Point HandleScrollbarHittest(const Scrollbar *sb, int top, int bottom)
return pt; return pt;
} }
/***************************************************** /** Special handling for the scrollbar widget type.
* Special handling for the scrollbar widget type.
* Handles the special scrolling buttons and other * Handles the special scrolling buttons and other
* scrolling. * scrolling.
* Parameters: * @param w Window on which a scroll was performed.
* w - Window. * @param wi Pointer to the scrollbar widget.
* wi - Pointer to the scrollbar widget. * @param x The X coordinate of the mouse click.
* x - The X coordinate of the mouse click. * @param y The Y coordinate of the mouse click. */
* y - The Y coordinate of the mouse click.
*/
void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y) void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y)
{ {
int mi, ma, pos; int mi, ma, pos;
@ -128,8 +124,8 @@ void ScrollbarClickHandler(Window *w, const Widget *wi, int x, int y)
/** Returns the index for the widget located at the given position /** Returns the index for the widget located at the given position
* relative to the window. It includes all widget-corner pixels as well. * relative to the window. It includes all widget-corner pixels as well.
* @param *w Window to look inside * @param *w Window to look inside
* @param x * @param x The Window client X coordinate
* @param y Window client coordinates * @param y The Window client y coordinate
* @return A widget index, or -1 if no widget was found. * @return A widget index, or -1 if no widget was found.
*/ */
int GetWidgetFromPos(const Window *w, int x, int y) int GetWidgetFromPos(const Window *w, int x, int y)
@ -737,7 +733,7 @@ static void ResizeWidgets(Window *w, byte a, byte b, byte c)
/** Evenly distribute some widgets when resizing horizontally (often a button row) /** Evenly distribute some widgets when resizing horizontally (often a button row)
* When only two arguments are given, the widgets are presumed to be on a line and only the ends are given * When only two arguments are given, the widgets are presumed to be on a line and only the ends are given
* @param w widow to modify * @param w Window to modify
* @param left The leftmost widget to resize * @param left The leftmost widget to resize
* @param right The rightmost widget to resize. Since right side of it is used, remember to set it to RESIZE_RIGHT * @param right The rightmost widget to resize. Since right side of it is used, remember to set it to RESIZE_RIGHT
*/ */

@ -1080,7 +1080,7 @@ static bool HandleMouseOver()
* Both the areas of the old window and the new sized window are set dirty * Both the areas of the old window and the new sized window are set dirty
* ensuring proper redrawal. * ensuring proper redrawal.
* @param w Window to resize * @param w Window to resize
* @param x delta x-size of changed window (positive if larger, etc.( * @param x delta x-size of changed window (positive if larger, etc.)
* @param y delta y-size of changed window */ * @param y delta y-size of changed window */
void ResizeWindow(Window *w, int x, int y) void ResizeWindow(Window *w, int x, int y)
{ {

Loading…
Cancel
Save