From c37002b4ea4d519c7922e8b5d0fd26a8a7c2894a Mon Sep 17 00:00:00 2001 From: DarkWyrm Date: Sun, 19 Jan 2003 23:04:58 +0000 Subject: [PATCH] More documentation tweaks git-svn-id: file:///srv/svn/repos/haiku/trunk/current@2517 a95241bf-73f2-0310-859d-f6bbb57e9c96 --- src/servers/app/server/ColorSet.cpp | 8 +- src/servers/app/server/DisplayDriver.cpp | 226 ++++++++++++----------- src/servers/app/server/FontFamily.cpp | 24 +-- src/servers/app/server/FontServer.cpp | 105 +++++++++-- src/servers/app/server/RGBColor.cpp | 56 +++--- src/servers/app/server/ServerBitmap.cpp | 16 +- src/servers/app/server/ServerCursor.cpp | 16 +- src/servers/app/server/ServerFont.cpp | 16 +- src/servers/app/server/SystemPalette.cpp | 4 +- 9 files changed, 273 insertions(+), 198 deletions(-) diff --git a/src/servers/app/server/ColorSet.cpp b/src/servers/app/server/ColorSet.cpp index c994b17550..f68492a2e8 100644 --- a/src/servers/app/server/ColorSet.cpp +++ b/src/servers/app/server/ColorSet.cpp @@ -8,7 +8,7 @@ ColorSet::ColorSet(void) /*! \brief Copy constructor which does a massive number of assignments - \param Color set to copy from + \param cs Color set to copy from */ ColorSet::ColorSet(const ColorSet &cs) { @@ -41,8 +41,8 @@ ColorSet::ColorSet(const ColorSet &cs) /*! \brief Overloaded assignment operator which does a massive number of assignments - \param Color set to copy from - \param The new values assigned to the color set + \param cs Color set to copy from + \return The new values assigned to the color set */ ColorSet & ColorSet::operator=(const ColorSet &cs) { @@ -53,7 +53,7 @@ ColorSet & ColorSet::operator=(const ColorSet &cs) /*! \brief Copy function which handles assignments, and, yes, *IT EVEN MAKES french fries!!* - \param Color set to copy from + \param cs Color set to copy from */ void ColorSet::SetColors(const ColorSet &cs) { diff --git a/src/servers/app/server/DisplayDriver.cpp b/src/servers/app/server/DisplayDriver.cpp index 6c237b8204..89d2749396 100644 --- a/src/servers/app/server/DisplayDriver.cpp +++ b/src/servers/app/server/DisplayDriver.cpp @@ -83,8 +83,8 @@ void DisplayDriver::Shutdown(void) /*! \brief Called for all BView::CopyBits calls - \param Source rectangle. - \param Destination rectangle. + \param src Source rectangle. + \param dest Destination rectangle. Bounds checking must be done in this call. If the destination is not the same size as the source, the source should be scaled to fit. @@ -95,11 +95,11 @@ void DisplayDriver::CopyBits(BRect src, BRect dest) /*! \brief Called for all BView::DrawBitmap calls - \param Bitmap to be drawn. It will always be non-NULL and valid. The color + \param bmp Bitmap to be drawn. It will always be non-NULL and valid. The color space is not guaranteed to match. - \param Source rectangle - \param Destination rectangle. Source will be scaled to fit if not the same size. - \param Data structure containing any other data necessary for the call. Always non-NULL. + \param src Source rectangle + \param dest Destination rectangle. Source will be scaled to fit if not the same size. + \param d Data structure containing any other data necessary for the call. Always non-NULL. Bounds checking must be done in this call. */ @@ -109,14 +109,14 @@ void DisplayDriver::DrawBitmap(ServerBitmap *bmp, BRect src, BRect dest, LayerDa /*! \brief Utilizes the font engine to draw a string to the frame buffer - \param String to be drawn. Always non-NULL. - \param Number of characters in the string to draw. Always greater than 0. If greater + \param string String to be drawn. Always non-NULL. + \param length Number of characters in the string to draw. Always greater than 0. If greater than the number of characters in the string, draw the entire string. - \param Point at which the baseline starts. Characters are to be drawn 1 pixel above + \param pt Point at which the baseline starts. Characters are to be drawn 1 pixel above this for backwards compatibility. While the point itself is guaranteed to be inside the frame buffers coordinate range, the clipping of each individual glyph must be performed by the driver itself. - \param Data structure containing any other data necessary for the call. Always non-NULL. + \param d Data structure containing any other data necessary for the call. Always non-NULL. */ void DisplayDriver::DrawString(const char *string, int32 length, BPoint pt, LayerData *d, escapement_delta *delta=NULL) { @@ -124,11 +124,11 @@ void DisplayDriver::DrawString(const char *string, int32 length, BPoint pt, Laye /*! \brief Called for all BView::FillArc calls - \param Rectangle enclosing the entire arc - \param Starting angle for the arc in degrees - \param Span of the arc in degrees. Ending angle = angle+span. - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param r Rectangle enclosing the entire arc + \param angle Starting angle for the arc in degrees + \param span Span of the arc in degrees. Ending angle = angle+span. + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. Bounds checking must be done in this call because only part of the arc may end up being clipped. @@ -139,10 +139,10 @@ void DisplayDriver::FillArc(BRect r, float angle, float span, LayerData *d, int8 /*! \brief Called for all BView::FillBezier calls. - \param 4-element array of BPoints in the order of start, end, and then the two control + \param pts 4-element array of BPoints in the order of start, end, and then the two control points. - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. Bounds checking must be done in this call. */ @@ -152,9 +152,9 @@ void DisplayDriver::FillBezier(BPoint *pts, LayerData *d, int8 *pat) /*! \brief Called for all BView::FillEllipse calls - \param BRect enclosing the ellipse to be drawn. - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param r BRect enclosing the ellipse to be drawn. + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. Bounds checking must be done in this call because only part of the ellipse may end up being clipped. @@ -165,11 +165,11 @@ void DisplayDriver::FillEllipse(BRect r, LayerData *d, int8 *pat) /*! \brief Called for all BView::FillPolygon calls - \param Array of BPoints defining the polygon. - \param Number of points in the BPoint array. - \param Rectangle which contains the polygon - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param ptlist Array of BPoints defining the polygon. + \param numpts Number of points in the BPoint array. + \param rect Rectangle which contains the polygon + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. The points in the array are not guaranteed to be within the framebuffer's coordinate range. @@ -180,9 +180,9 @@ void DisplayDriver::FillPolygon(BPoint *ptlist, int32 numpts, BRect rect, LayerD /*! \brief Called for all BView::FillRect calls - \param BRect to be filled. Guaranteed to be in the frame buffer's coordinate space - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param r BRect to be filled. Guaranteed to be in the frame buffer's coordinate space + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. */ void DisplayDriver::FillRect(BRect r, LayerData *d, int8 *pat) @@ -191,10 +191,11 @@ void DisplayDriver::FillRect(BRect r, LayerData *d, int8 *pat) /*! \brief Called for all BView::FillRoundRect calls - \param X radius of the corner arcs - \param Y radius of the corner arcs - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param r The rectangle itself + \param xrad X radius of the corner arcs + \param yrad Y radius of the corner arcs + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. Bounds checking must be done in this call because only part of the roundrect may end up being clipped. @@ -209,11 +210,11 @@ void DisplayDriver::FillRoundRect(BRect r, float xrad, float yrad, LayerData *d, /*! \brief Called for all BView::FillTriangle calls - \param Array of 3 BPoints. Always non-NULL. - \param BRect enclosing the triangle. While it will definitely enclose the triangle, + \param pts Array of 3 BPoints. Always non-NULL. + \param r BRect enclosing the triangle. While it will definitely enclose the triangle, it may not be within the frame buffer's bounds. - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. Bounds checking must be done in this call because only part of the triangle may end up being clipped. @@ -265,7 +266,7 @@ void DisplayDriver::MoveCursorTo(float x, float y) /*! \brief Inverts the colors in the rectangle. - \param Rectangle of the area to be inverted. Guaranteed to be within bounds. + \param r Rectangle of the area to be inverted. Guaranteed to be within bounds. */ void DisplayDriver::InvertRect(BRect r) { @@ -300,7 +301,7 @@ void DisplayDriver::ObscureCursor(void) /*! \brief Changes the cursor. - \param The new cursor. Guaranteed to be non-NULL. + \param cursor The new cursor. Guaranteed to be non-NULL. The driver does not take ownership of the given cursor. Subclasses should make a copy of the cursor passed to it. The default version of this function hides the @@ -324,11 +325,11 @@ void DisplayDriver::SetCursor(ServerCursor *cursor) /*! \brief Called for all BView::StrokeArc calls - \param Rectangle enclosing the entire arc - \param Starting angle for the arc in degrees - \param Span of the arc in degrees. Ending angle = angle+span. - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param r Rectangle enclosing the entire arc + \param angle Starting angle for the arc in degrees + \param span Span of the arc in degrees. Ending angle = angle+span. + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. Bounds checking must be done in this call because only part of the arc may end up being clipped. @@ -338,10 +339,10 @@ void DisplayDriver::SetCursor(ServerCursor *cursor) /*! \brief Called for all BView::StrokeBezier calls. - \param 4-element array of BPoints in the order of start, end, and then the two control + \param pts 4-element array of BPoints in the order of start, end, and then the two control points. - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. Bounds checking must be done in this call. */ @@ -351,9 +352,9 @@ void DisplayDriver::StrokeBezier(BPoint *pts, LayerData *d, int8 *pat) /*! \brief Called for all BView::StrokeEllipse calls - \param BRect enclosing the ellipse to be drawn. - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param r BRect enclosing the ellipse to be drawn. + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. Bounds checking must be done in this call because only part of the ellipse may end up being clipped. @@ -364,10 +365,10 @@ void DisplayDriver::StrokeEllipse(BRect r, LayerData *d, int8 *pat) /*! \brief Draws a line. Really. - \param Starting point - \param Ending point - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param start Starting point + \param end Ending point + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. The endpoints themselves are guaranteed to be in bounds, but clipping for lines with a thickness greater than 1 will need to be done. @@ -378,11 +379,11 @@ void DisplayDriver::StrokeLine(BPoint start, BPoint end, LayerData *d, int8 *pat /*! \brief Called for all BView::StrokePolygon calls - \param Array of BPoints defining the polygon. - \param Number of points in the BPoint array. - \param Rectangle which contains the polygon - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param ptlist Array of BPoints defining the polygon. + \param numpts Number of points in the BPoint array. + \param rect Rectangle which contains the polygon + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. The points in the array are not guaranteed to be within the framebuffer's coordinate range. @@ -393,9 +394,9 @@ void DisplayDriver::StrokePolygon(BPoint *ptlist, int32 numpts, BRect rect, Laye /*! \brief Called for all BView::StrokeRect calls - \param BRect to be filled. Guaranteed to be in the frame buffer's coordinate space - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param r BRect to be filled. Guaranteed to be in the frame buffer's coordinate space + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. */ void DisplayDriver::StrokeRect(BRect r, LayerData *d, int8 *pat) @@ -404,10 +405,11 @@ void DisplayDriver::StrokeRect(BRect r, LayerData *d, int8 *pat) /*! \brief Called for all BView::StrokeRoundRect calls - \param X radius of the corner arcs - \param Y radius of the corner arcs - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param r The rect itself + \param xrad X radius of the corner arcs + \param yrad Y radius of the corner arcs + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. Bounds checking must be done in this call because only part of the roundrect may end up being clipped. @@ -422,11 +424,11 @@ void DisplayDriver::StrokeRoundRect(BRect r, float xrad, float yrad, LayerData * /*! \brief Called for all BView::StrokeTriangle calls - \param Array of 3 BPoints. Always non-NULL. - \param BRect enclosing the triangle. While it will definitely enclose the triangle, + \param pts Array of 3 BPoints. Always non-NULL. + \param r BRect enclosing the triangle. While it will definitely enclose the triangle, it may not be within the frame buffer's bounds. - \param Data structure containing any other data necessary for the call. Always non-NULL. - \param 8-byte array containing the pattern to use. Always non-NULL. + \param d Data structure containing any other data necessary for the call. Always non-NULL. + \param pat 8-byte array containing the pattern to use. Always non-NULL. Bounds checking must be done in this call because only part of the triangle may end up being clipped. @@ -437,10 +439,10 @@ void DisplayDriver::StrokeTriangle(BPoint *pts, BRect r, LayerData *d, int8 *pat /*! \brief Draws a series of lines - optimized for speed - \param Array of BPoints pairs - \param Number of lines to be drawn - \param Array of colors for each respective line - \param Data structure containing any other data necessary for the call. Always non-NULL. + \param pts Array of BPoints pairs + \param numlines Number of lines to be drawn + \param colors Array of colors for each respective line + \param d Data structure containing any other data necessary for the call. Always non-NULL. Data for this call is passed directly from userland - this call is responsible for all checking. All lines are to be processed in the call using the same LayerData settings @@ -452,7 +454,7 @@ void DisplayDriver::StrokeLineArray(BPoint *pts, int32 numlines, RGBColor *color /*! \brief Sets the screen mode to specified resolution and color depth. - \param constant as defined in GraphicsDefs.h + \param mode constant as defined in GraphicsDefs.h Subclasses must include calls to _SetDepth, _SetHeight, _SetWidth, and _SetMode to update the state variables kept internally by the DisplayDriver class. @@ -463,7 +465,7 @@ void DisplayDriver::SetMode(int32 mode) /*! \brief Dumps the contents of the frame buffer to a file. - \param Path and leaf of the file to be created without an extension + \param path Path and leaf of the file to be created without an extension \return False if unimplemented or unsuccessful. True if otherwise. Subclasses should add an extension based on what kind of file is saved @@ -475,9 +477,9 @@ bool DisplayDriver::DumpToFile(const char *path) /*! \brief Gets the width of a string in pixels - \param Source null-terminated string - \param Number of characters in the string - \param Data structure containing any other data necessary for the call. Always non-NULL. + \param string Source null-terminated string + \param length Number of characters in the string + \param d Data structure containing any other data necessary for the call. Always non-NULL. \return Width of the string in pixels This corresponds to BView::StringWidth. @@ -489,9 +491,9 @@ float DisplayDriver::StringWidth(const char *string, int32 length, LayerData *d) /*! \brief Gets the height of a string in pixels - \param Source null-terminated string - \param Number of characters in the string - \param Data structure containing any other data necessary for the call. Always non-NULL. + \param string Source null-terminated string + \param length Number of characters in the string + \param d Data structure containing any other data necessary for the call. Always non-NULL. \return Height of the string in pixels The height calculated in this function does not include any padding - just the @@ -506,12 +508,12 @@ float DisplayDriver::StringHeight(const char *string, int32 length, LayerData *d /*! \brief Retrieves the bounding box each character in the string - \param Source null-terminated string - \param Number of characters in the string - \param Metrics mode for either screen or printing - \param Optional glyph padding. This value may be NULL. - \param Array of BRect objects which will have at least count elements - \param Data structure containing any other data necessary for the call. Always non-NULL. + \param string Source null-terminated string + \param count Number of characters in the string + \param mode Metrics mode for either screen or printing + \param delta Optional glyph padding. This value may be NULL. + \param rectarray Array of BRect objects which will have at least count elements + \param d Data structure containing any other data necessary for the call. Always non-NULL. See BFont::GetBoundingBoxes for more details on this function. */ @@ -522,14 +524,14 @@ void DisplayDriver::GetBoundingBoxes(const char *string, int32 count, /*! \brief Retrieves the escapements for each character in the string - \param Source null-terminated string - \param Number of characters in the string - \param Optional glyph padding. This value may be NULL. - \param Array of escapement_delta objects which will have at least charcount elements - \param Actual offset values when iterating over the string. This array will also + \param string Source null-terminated string + \param charcount Number of characters in the string + \param delta Optional glyph padding. This value may be NULL. + \param escapements Array of escapement_delta objects which will have at least charcount elements + \param offsets Actual offset values when iterating over the string. This array will also have at least charcount elements and the values placed therein will reflect the current kerning/spacing mode. - \param Data structure containing any other data necessary for the call. Always non-NULL. + \param d Data structure containing any other data necessary for the call. Always non-NULL. See BFont::GetEscapements for more details on this function. */ @@ -540,10 +542,10 @@ void DisplayDriver::GetEscapements(const char *string, int32 charcount, /*! \brief Retrieves the inset values of each glyph from its escapement values - \param Source null-terminated string - \param Number of characters in the string - \param Array of edge_info objects which will have at least charcount elements - \param Data structure containing any other data necessary for the call. Always non-NULL. + \param string Source null-terminated string + \param charcount Number of characters in the string + \param edgearray Array of edge_info objects which will have at least charcount elements + \param d Data structure containing any other data necessary for the call. Always non-NULL. See BFont::GetEdges for more details on this function. */ @@ -553,9 +555,9 @@ void DisplayDriver::GetEdges(const char *string, int32 charcount, edge_info *edg /*! \brief Determines whether a font contains a certain string of characters - \param Source null-terminated string - \param Number of characters in the string - \param Array of booleans which will have at least charcount elements + \param string Source null-terminated string + \param charcount Number of characters in the string + \param hasarray Array of booleans which will have at least charcount elements See BFont::GetHasGlyphs for more details on this function. */ @@ -565,11 +567,11 @@ void DisplayDriver::GetHasGlyphs(const char *string, int32 charcount, bool *hasa /*! \brief Truncates an array of strings to a certain width - \param Array of null-terminated strings - \param Number of strings passed to the function - \param Truncation mode - \param Maximum width for all strings - \param String array provided by the caller into which the truncated strings are + \param instrings Array of null-terminated strings + \param stringcount Number of strings passed to the function + \param mode Truncation mode + \param maxwidth Maximum width for all strings + \param outstrings String array provided by the caller into which the truncated strings are to be placed. See BFont::GetTruncatedStrings for more details on this function. @@ -628,8 +630,8 @@ bool DisplayDriver::IsCursorObscured(bool state) /*! \brief Locks the driver - \param Optional timeout specifier - \param True if the lock was successful, false if not. + \param timeout Optional timeout specifier + \return True if the lock was successful, false if not. The return value need only be checked if a timeout was specified. Each public member function should lock the driver before doing anything else. Functions @@ -652,7 +654,7 @@ void DisplayDriver::_Unlock(void) /*! \brief Internal depth-setting function - \param Number of bits per pixel in use + \param d Number of bits per pixel in use _SetDepth must be called from within any implementation of SetMode */ @@ -663,7 +665,7 @@ void DisplayDriver::_SetDepth(uint8 d) /*! \brief Internal height-setting function - \param Height of the frame buffer + \param h Height of the frame buffer _SetHeight must be called from within any implementation of SetMode */ @@ -674,7 +676,7 @@ void DisplayDriver::_SetHeight(uint16 h) /*! \brief Internal width-setting function - \param Width of the frame buffer + \param w Width of the frame buffer _SetWidth must be called from within any implementation of SetMode */ @@ -685,7 +687,7 @@ void DisplayDriver::_SetWidth(uint16 w) /*! \brief Internal mode-setting function. - \param Screen mode in use as defined in GraphicsDefs.h + \param m Screen mode in use as defined in GraphicsDefs.h _SetMode must be called from within any implementation of SetMode. Note that this does not actually change the screen mode; it just updates the state variable used diff --git a/src/servers/app/server/FontFamily.cpp b/src/servers/app/server/FontFamily.cpp index 6a1c090d4c..1782256c65 100644 --- a/src/servers/app/server/FontFamily.cpp +++ b/src/servers/app/server/FontFamily.cpp @@ -32,7 +32,7 @@ extern FTC_Manager ftmanager; /*! \brief Constructor - \param path to a font file + \param filepath path to a font file \param face FreeType handle for the font file after it is loaded - for its info only */ FontStyle::FontStyle(const char *filepath, FT_Face face) @@ -113,7 +113,7 @@ const char *FontStyle::GetPath(void) /*! \brief Converts an ASCII character to Unicode for the style - \param An ASCII character + \param c An ASCII character \return A Unicode value for the character */ int16 FontStyle::ConvertToUnicode(uint16 c) @@ -127,9 +127,9 @@ int16 FontStyle::ConvertToUnicode(uint16 c) /*! \brief Creates a new ServerFont object for the style, given size, shear, and rotation. - \param character size in points - \param rotation in degrees - \param shear (slant) in degrees. 45 <= shear <= 135. 90 is vertical + \param size character size in points + \param rotation rotation in degrees + \param shear shear (slant) in degrees. 45 <= shear <= 135. 90 is vertical \return The new ServerFont object */ ServerFont *FontStyle::Instantiate(float size, float rotation=0.0, float shear=90.0) @@ -141,7 +141,7 @@ ServerFont *FontStyle::Instantiate(float size, float rotation=0.0, float shear=9 /*! \brief Constructor - \param Name of the family + \param namestr Name of the family */ FontFamily::FontFamily(const char *namestr) { @@ -182,8 +182,8 @@ const char *FontFamily::Name(void) /*! \brief Adds the style to the family - \param full path to the style's font file - \param FreeType face handle used to obtain info about the font + \param path full path to the style's font file + \param face FreeType face handle used to obtain info about the font */ void FontFamily::AddStyle(const char *path,FT_Face face) { @@ -210,7 +210,7 @@ void FontFamily::AddStyle(const char *path,FT_Face face) /*! \brief Removes a style from the family and deletes it - \param Name of the style to be removed from the family + \param style Name of the style to be removed from the family */ void FontFamily::RemoveStyle(const char *style) { @@ -245,7 +245,7 @@ int32 FontFamily::CountStyles(void) /*! \brief Determines whether the style belongs to the family - \param Name of the style being checked + \param style Name of the style being checked \return True if it belongs, false if not */ bool FontFamily::HasStyle(const char *style) @@ -265,7 +265,7 @@ bool FontFamily::HasStyle(const char *style) /*! \brief Returns the name of a style in the family - \param list index of the style to be found + \param index list index of the style to be found \return name of the style or NULL if the index is not valid */ const char *FontFamily::GetStyle(int32 index) @@ -278,7 +278,7 @@ const char *FontFamily::GetStyle(int32 index) /*! \brief Get the FontStyle object for the name given - \param Name of the style to be obtained + \param style Name of the style to be obtained \return The FontStyle object or NULL if none was found. The object returned belongs to the family and must not be deleted. diff --git a/src/servers/app/server/FontServer.cpp b/src/servers/app/server/FontServer.cpp index eb9d78da56..3219d4c6c2 100644 --- a/src/servers/app/server/FontServer.cpp +++ b/src/servers/app/server/FontServer.cpp @@ -41,6 +41,9 @@ FTC_Manager ftmanager; FT_Library ftlib; FontServer *fontserver; +/*! + \brief Access function to request a face via the FreeType font cache +*/ static FT_Error face_requester(FTC_FaceID face_id, FT_Library library, FT_Pointer request_data, FT_Face *aface) { @@ -48,7 +51,7 @@ static FT_Error face_requester(FTC_FaceID face_id, FT_Library library, return FT_New_Face(ftlib,face->file_path.String(),face->face_index,aface); } - +//! Does basic set up so that directories can be scanned FontServer::FontServer(void) { lock=create_sem(1,"fontserver_lock"); @@ -71,6 +74,7 @@ FontServer::FontServer(void) fixed=NULL; } +//! Frees items allocated in the constructor and shuts down FreeType FontServer::~FontServer(void) { delete_sem(lock); @@ -79,16 +83,22 @@ FontServer::~FontServer(void) FT_Done_FreeType(ftlib); } +//! Locks access to the font server void FontServer::Lock(void) { acquire_sem(lock); } +//! Unlocks access to the font server void FontServer::Unlock(void) { release_sem(lock); } +/*! + \brief Counts the number of font families available + \return The number of unique font families currently available +*/ int32 FontServer::CountFamilies(void) { if(init) @@ -96,6 +106,11 @@ int32 FontServer::CountFamilies(void) return 0; } +/*! + \brief Counts the number of styles available in a font family + \param family Name of the font family to scan + \return The number of font styles currently available for the font family +*/ int32 FontServer::CountStyles(const char *family) { FontFamily *f=_FindFamily(family); @@ -106,6 +121,10 @@ int32 FontServer::CountStyles(const char *family) return 0; } +/*! + \brief Removes a font family from the font list + \param family The family to remove +*/ void FontServer::RemoveFamily(const char *family) { FontFamily *f=_FindFamily(family); @@ -116,6 +135,13 @@ void FontServer::RemoveFamily(const char *family) } } +/*! + \brief Protected function which locates a FontFamily object + \param name The family to find + \return Pointer to the specified family or NULL if not found. + + Do NOT delete the FontFamily returned by this function. +*/ FontFamily *FontServer::_FindFamily(const char *name) { if(!init) @@ -131,15 +157,26 @@ FontFamily *FontServer::_FindFamily(const char *name) return NULL; } +/*! + \brief Scan a folder for all valid fonts + \param fontspath Path of the folder to scan. + \return + - \c B_OK Success + - \c B_NAME_TOO_LONG The path specified is too long + - \c B_ENTRY_NOT_FOUND The path does not exist + - \c B_LINK_LIMIT A cyclic loop was detected in the file system + - \c B_BAD_VALUE Invalid input specified + - \c B_NO_MEMORY Insufficient memory to open the folder for reading + - \c B_BUSY A busy node could not be accessed + - \c B_FILE_ERROR An invalid file prevented the operation. + - \c B_NO_MORE_FDS All file descriptors are in use (too many open files). +*/ status_t FontServer::ScanDirectory(const char *fontspath) { // This bad boy does all the real work. It loads each entry in the // directory. If a valid font file, it adds both the family and the style. // Both family and style are stored internally as BStrings. Once everything -#ifdef DEBUG_SCANDIR -printf("FontServer::ScanDirectory(%s)\n",fontspath); -#endif BDirectory dir; BEntry entry; BPath path; @@ -150,7 +187,6 @@ printf("FontServer::ScanDirectory(%s)\n",fontspath); FT_Error error; FT_CharMap charmap; FontFamily *family; -// int32 familycount; stat=dir.SetTo(fontspath); if(stat!=B_OK) @@ -208,6 +244,12 @@ printf("FontServer::ScanDirectory(%s)\n",fontspath); return B_OK; } +/*! + \brief Finds and returns the first valid charmap in a font + + \param face Font handle obtained from FT_Load_Face() + \return An FT_CharMap or NULL if unsuccessful +*/ FT_CharMap FontServer::_GetSupportedCharmap(const FT_Face &face) { int32 i; @@ -248,20 +290,19 @@ FT_CharMap FontServer::_GetSupportedCharmap(const FT_Face &face) } -/* -This saves all family names and styles to the file -/boot/home/config/app_server/fontlist as a flattened BMessage +/*! + \brief This saves all family names and styles to the file specified in + ServerConfig.h as SERVER_FONT_LIST as a flattened BMessage. -This operation is not done very often because the access to disk adds a significant -performance hit. + This operation is not done very often because the access to disk adds a significant + performance hit. -The format for storage consists of two things: an array of strings with the name 'family' -and a number of small string arrays which have the name of the font family. These are -the style lists. - -Additionally, any fonts which have bitmap strikes contained in them or any fonts which -are fixed-width are named in the arrays 'tuned' and 'fixed' + The format for storage consists of two things: an array of strings with the name 'family' + and a number of small string arrays which have the name of the font family. These are + the style lists. + Additionally, any fonts which have bitmap strikes contained in them or any fonts which + are fixed-width are named in the arrays 'tuned' and 'fixed'. */ void FontServer::SaveList(void) { @@ -322,6 +363,12 @@ void FontServer::SaveList(void) fontmsg.Flatten(&file); } +/*! + \brief Retrieves the FontStyle object + \param family The font's family + \param face The font's style + \return The FontStyle having those attributes or NULL if not available +*/ FontStyle *FontServer::GetStyle(font_family family, font_style face) { FontFamily *ffam=_FindFamily(family); @@ -334,6 +381,12 @@ FontStyle *FontServer::GetStyle(font_family family, font_style face) return NULL; } +/*! + \brief Returns the current object used for the regular style + \return A ServerFont pointer which is the plain font. + + Do NOT delete this object. If you access it, make a copy of it. +*/ ServerFont *FontServer::GetSystemPlain(void) { if(plain) @@ -344,6 +397,12 @@ ServerFont *FontServer::GetSystemPlain(void) return NULL; } +/*! + \brief Returns the current object used for the bold style + \return A ServerFont pointer which is the bold font. + + Do NOT delete this object. If you access it, make a copy of it. +*/ ServerFont *FontServer::GetSystemBold(void) { if(bold) @@ -354,6 +413,12 @@ ServerFont *FontServer::GetSystemBold(void) return NULL; } +/*! + \brief Returns the current object used for the fixed style + \return A ServerFont pointer which is the fixed font. + + Do NOT delete this object. If you access it, make a copy of it. +*/ ServerFont *FontServer::GetSystemFixed(void) { if(fixed) @@ -364,6 +429,14 @@ ServerFont *FontServer::GetSystemFixed(void) return NULL; } +/*! + \brief Sets the system's plain font to the specified family and style + \param family Name of the font's family + \param style Name of the style desired + \param size Size desired + \return true if successful, false if not. + +*/ bool FontServer::SetSystemPlain(const char *family, const char *style, float size) { FontFamily *fam=_FindFamily(family); diff --git a/src/servers/app/server/RGBColor.cpp b/src/servers/app/server/RGBColor.cpp index 617b521896..7119e4f554 100644 --- a/src/servers/app/server/RGBColor.cpp +++ b/src/servers/app/server/RGBColor.cpp @@ -35,10 +35,10 @@ /*! \brief Create an RGBColor from specified values - \param red - \param green - \param blue - \param alpha, defaults to 255 + \param red red + \param green green + \param blue blue + \param alpha alpha, defaults to 255 */ RGBColor::RGBColor(uint8 r, uint8 g, uint8 b, uint8 a) { @@ -47,10 +47,10 @@ RGBColor::RGBColor(uint8 r, uint8 g, uint8 b, uint8 a) /*! \brief Create an RGBColor from specified values - \param red - \param green - \param blue - \param alpha, defaults to 255 + \param red red + \param green green + \param blue blue + \param alpha alpha, defaults to 255 */ RGBColor::RGBColor(int r, int g, int b, int a=255) { @@ -59,7 +59,7 @@ RGBColor::RGBColor(int r, int g, int b, int a=255) /*! \brief Create an RGBColor from an rgb_color - \param color to initialize from + \param col color to initialize from */ RGBColor::RGBColor(const rgb_color &col) { @@ -68,7 +68,7 @@ RGBColor::RGBColor(const rgb_color &col) /*! \brief Create an RGBColor from a 16-bit RGBA color - \param color to initialize from + \param col color to initialize from */ RGBColor::RGBColor(uint16 col) { @@ -77,7 +77,7 @@ RGBColor::RGBColor(uint16 col) /*! \brief Create an RGBColor from an index color - \param color to initialize from + \param col color to initialize from */ RGBColor::RGBColor(uint8 col) { @@ -86,7 +86,7 @@ RGBColor::RGBColor(uint8 col) /*! \brief Copy Contructor - \param color to initialize from + \param col color to initialize from */ RGBColor::RGBColor(const RGBColor &col) { @@ -132,10 +132,10 @@ rgb_color RGBColor::GetColor32(void) /*! \brief Set the object to specified values - \param red - \param green - \param blue - \param alpha, defaults to 255 + \param red red + \param green green + \param blue blue + \param alpha alpha, defaults to 255 */ void RGBColor::SetColor(uint8 r, uint8 g, uint8 b, uint8 a=255) { @@ -147,10 +147,10 @@ void RGBColor::SetColor(uint8 r, uint8 g, uint8 b, uint8 a=255) /*! \brief Set the object to specified values - \param red - \param green - \param blue - \param alpha, defaults to 255 + \param red red + \param green green + \param blue blue + \param alpha alpha, defaults to 255 */ void RGBColor::SetColor(int r, int g, int b, int a=255) { @@ -162,7 +162,7 @@ void RGBColor::SetColor(int r, int g, int b, int a=255) /*! \brief Set the object to specified value - \param color to copy + \param col16 color to copy */ void RGBColor::SetColor(uint16 col16) { @@ -173,7 +173,7 @@ void RGBColor::SetColor(uint16 col16) /*! \brief Set the object to specified index in the palette - \param color to copy + \param col8 color to copy */ void RGBColor::SetColor(uint8 col8) { @@ -184,7 +184,7 @@ void RGBColor::SetColor(uint8 col8) /*! \brief Set the object to specified color - \param color to copy + \param color color to copy */ void RGBColor::SetColor(const rgb_color &color) { @@ -195,7 +195,7 @@ void RGBColor::SetColor(const rgb_color &color) /*! \brief Set the object to specified color - \param color to copy + \param col color to copy */ void RGBColor::SetColor(const RGBColor &col) { @@ -206,7 +206,7 @@ void RGBColor::SetColor(const RGBColor &col) /*! \brief Set the object to specified color - \param color to copy + \param col color to copy */ RGBColor & RGBColor::operator=(const RGBColor &col) { @@ -218,7 +218,7 @@ RGBColor & RGBColor::operator=(const RGBColor &col) /*! \brief Set the object to specified color - \param color to copy + \param col color to copy */ RGBColor & RGBColor::operator=(const rgb_color &col) { @@ -233,8 +233,8 @@ RGBColor & RGBColor::operator=(const rgb_color &col) \brief Returns a color blended between the object's value and another color. - \param The other color to be blended with. - \param A weighted percentage of the second color to use. 0 <= value <= 1.0 + \param color The other color to be blended with. + \param position A weighted percentage of the second color to use. 0 <= value <= 1.0 \return The blended color If the position passed to this function is invalid, the starting diff --git a/src/servers/app/server/ServerBitmap.cpp b/src/servers/app/server/ServerBitmap.cpp index d68bbf489d..4d00102d28 100644 --- a/src/servers/app/server/ServerBitmap.cpp +++ b/src/servers/app/server/ServerBitmap.cpp @@ -28,13 +28,13 @@ /*! \brief Constructor called by the BitmapManager (only). - \param Size of the bitmap. - \param Color space of the bitmap - \param Various bitmap flags to tweak the bitmap as defined in Bitmap.h - \param Number of bytes in each row. -1 implies the default value. Any value less - than the the default will less than the default will be overridden, but any value + \param rect Size of the bitmap. + \param space Color space of the bitmap + \param flags Various bitmap flags to tweak the bitmap as defined in Bitmap.h + \param bytesperline Number of bytes in each row. -1 implies the default value. Any + value less than the the default will less than the default will be overridden, but any value greater than the default will result in the number of bytes specified. - \param Screen assigned to the bitmap. + \param screen Screen assigned to the bitmap. */ ServerBitmap::ServerBitmap(BRect rect,color_space space, int32 flags, int32 bytesperline=-1, screen_id screen=B_MAIN_SCREEN_ID) @@ -97,8 +97,8 @@ uint32 ServerBitmap::BitsLength(void) /*! \brief Internal function used to translate color space values to appropriate internal values. - \param Color space for the bitmap. - \param Number of bytes per row. + \param space Color space for the bitmap. + \param bytesperline Number of bytes per row. */ void ServerBitmap::_HandleSpace(color_space space, int32 bytesperline=-1) { diff --git a/src/servers/app/server/ServerCursor.cpp b/src/servers/app/server/ServerCursor.cpp index 079127a055..830b851e61 100644 --- a/src/servers/app/server/ServerCursor.cpp +++ b/src/servers/app/server/ServerCursor.cpp @@ -28,11 +28,11 @@ /*! \brief Constructor - \param Size of the cursor - \param Color space of the cursor - \param ServerBitmap flags. See Bitmap.h. - \param Hotspot of the cursor - \param Bytes per row for the cursor. See ServerBitmap::ServerBitmap() + \param r Size of the cursor + \param cspace Color space of the cursor + \param flags ServerBitmap flags. See Bitmap.h. + \param hotspot Hotspot of the cursor + \param bytesperline Bytes per row for the cursor. See ServerBitmap::ServerBitmap() */ ServerCursor::ServerCursor(BRect r, color_space cspace, int32 flags, BPoint hotspot, int32 bytesperrow=-1, screen_id screen=B_MAIN_SCREEN_ID) @@ -46,7 +46,7 @@ ServerCursor::ServerCursor(BRect r, color_space cspace, int32 flags, BPoint hots /*! \brief Constructor - \param pointer to 68-byte cursor data array. See BeBook entry for BCursor for details + \param data pointer to 68-byte cursor data array. See BeBook entry for BCursor for details */ ServerCursor::ServerCursor(int8 *data) : ServerBitmap(BRect(0,0,15,15),B_RGBA32,0,64) @@ -104,7 +104,7 @@ ServerCursor::ServerCursor(int8 *data) /*! \brief Copy constructor - \param cursor to copy + \param cursor cursor to copy */ ServerCursor::ServerCursor(const ServerCursor *cursor) : ServerBitmap(cursor) @@ -128,7 +128,7 @@ ServerCursor::~ServerCursor(void) /*! \brief Sets the cursor's hotspot - \param New location of hotspot, constrained to the cursor's boundaries. + \param pt New location of hotspot, constrained to the cursor's boundaries. */ void ServerCursor::SetHotSpot(BPoint pt) { diff --git a/src/servers/app/server/ServerFont.cpp b/src/servers/app/server/ServerFont.cpp index 8142b1eb81..df67384d07 100644 --- a/src/servers/app/server/ServerFont.cpp +++ b/src/servers/app/server/ServerFont.cpp @@ -30,12 +30,12 @@ /*! \brief Constructor - \param Style object to which the ServerFont belongs - \param Character size in points - \param Rotation in degrees - \param Shear (slant) in degrees. 45 <= shear <= 135 - \param Style flags as defined in - \spacing String spacing flag as defined in + \param style Style object to which the ServerFont belongs + \param size Character size in points + \param rotation Rotation in degrees + \param shear Shear (slant) in degrees. 45 <= shear <= 135 + \param flags Style flags as defined in + \param spacing String spacing flag as defined in */ ServerFont::ServerFont(FontStyle *style, float size, float rotation, float shear, uint16 flags, uint8 spacing) @@ -57,7 +57,7 @@ ServerFont::ServerFont(FontStyle *style, float size, float rotation, float shear /*! \brief Copy Constructor - \param ServerFont to copy + \param font ServerFont to copy */ ServerFont::ServerFont(const ServerFont &font) { @@ -118,7 +118,7 @@ BRect ServerFont::BoundingBox(void) /*! \brief Obtains the height values for characters in the font in its current state - \param pointer to a font_height object to receive the values for the font + \param fh pointer to a font_height object to receive the values for the font */ void ServerFont::Height(font_height *fh) { diff --git a/src/servers/app/server/SystemPalette.cpp b/src/servers/app/server/SystemPalette.cpp index df6388d09e..5505e075f0 100644 --- a/src/servers/app/server/SystemPalette.cpp +++ b/src/servers/app/server/SystemPalette.cpp @@ -38,8 +38,8 @@ rgb_color system_palette[256]; /*! - \brief Takes a 256-element rgb_color array and places the BeOS System - palette in it. + \brief Takes a palette array and places the BeOS System palette in it. + \param palette 256-element rgb_color array */ void GenerateSystemPalette(rgb_color *palette) {