[haiku-commits] haiku: hrev45242 - in docs/user: support app
- From: jscipione@xxxxxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Thu, 7 Feb 2013 20:19:48 +0100 (CET)
hrev45242 adds 1 changeset to branch 'master'
old head: 6dc7e05ecf9371c87c58efa09c1656e500c0ff44
new head: db5b891db2923d1787c15b9c97f0e49a30949fdb
overview: http://cgit.haiku-os.org/haiku/log/?qt=range&q=db5b891+%5E6dc7e05
----------------------------------------------------------------------------
db5b891: Move app and support class docs from libbe to libroot.
Also a few more style and spelling fixes.
[ John Scipione <jscipione@xxxxxxxxx> ]
----------------------------------------------------------------------------
Revision: hrev45242
Commit: db5b891db2923d1787c15b9c97f0e49a30949fdb
URL: http://cgit.haiku-os.org/haiku/commit/?id=db5b891
Author: John Scipione <jscipione@xxxxxxxxx>
Date: Thu Feb 7 19:19:09 2013 UTC
----------------------------------------------------------------------------
22 files changed, 75 insertions(+), 62 deletions(-)
docs/user/app/Application.dox | 2 +-
docs/user/app/Clipboard.dox | 2 +-
docs/user/app/Cursor.dox | 2 +-
docs/user/app/Handler.dox | 2 +-
docs/user/app/Looper.dox | 2 +-
docs/user/app/Message.dox | 2 +-
docs/user/app/MessageFilter.dox | 3 +--
docs/user/app/MessageQueue.dox | 25 +++++++++++++------------
docs/user/support/Archivable.dox | 4 ++--
docs/user/support/Archiver.dox | 4 ++--
docs/user/support/Autolock.dox | 4 ++--
docs/user/support/Beep.dox | 2 +-
docs/user/support/BlockCache.dox | 26 +++++++++++++-------------
docs/user/support/BufferIO.dox | 5 ++---
docs/user/support/DataIO.dox | 4 ++--
docs/user/support/Flattenable.dox | 4 ++--
docs/user/support/List.dox | 4 ++--
docs/user/support/Locker.dox | 32 +++++++++++++++++++++++---------
docs/user/support/String.dox | 2 +-
docs/user/support/SupportDefs.dox | 2 +-
docs/user/support/Unarchiver.dox | 2 +-
docs/user/support/stopwatch.dox | 2 +-
----------------------------------------------------------------------------
diff --git a/docs/user/app/Application.dox b/docs/user/app/Application.dox
index aa18fea..a3f4ec6 100644
--- a/docs/user/app/Application.dox
+++ b/docs/user/app/Application.dox
@@ -22,7 +22,7 @@
/*!
\class BApplication
\ingroup app
- \ingroup libbe
+ \ingroup libroot
\brief A container object for an application.
A BApplication establishes a connection between the application and the
diff --git a/docs/user/app/Clipboard.dox b/docs/user/app/Clipboard.dox
index f1fbbc2..079fe95 100644
--- a/docs/user/app/Clipboard.dox
+++ b/docs/user/app/Clipboard.dox
@@ -29,7 +29,7 @@
/*!
\class BClipboard
\ingroup app
- \ingroup libbe
+ \ingroup libroot
\brief Used for short-term data storage between documents and
applications via copy and paste operations.
diff --git a/docs/user/app/Cursor.dox b/docs/user/app/Cursor.dox
index 4b266d8..d80e2a9 100644
--- a/docs/user/app/Cursor.dox
+++ b/docs/user/app/Cursor.dox
@@ -202,7 +202,7 @@
/*!
\class BCursor
\ingroup app
- \ingroup libbe
+ \ingroup libroot
\brief BCursor describes a view-wide or application-wide cursor.
\note As BeOS only supports 16x16 monochrome cursors, to see a nice
diff --git a/docs/user/app/Handler.dox b/docs/user/app/Handler.dox
index 2279718..50f9cfd 100644
--- a/docs/user/app/Handler.dox
+++ b/docs/user/app/Handler.dox
@@ -55,7 +55,7 @@
/*!
\class BHandler
\ingroup app
- \ingroup libbe
+ \ingroup libroot
\brief Handles messages that are passed on by a BLooper.
The BHandler class implements two important pieces of functionality. It
diff --git a/docs/user/app/Looper.dox b/docs/user/app/Looper.dox
index b3ac2e9..525679b 100644
--- a/docs/user/app/Looper.dox
+++ b/docs/user/app/Looper.dox
@@ -27,7 +27,7 @@
/*!
\class BLooper
\ingroup app
- \ingroup libbe
+ \ingroup libroot
\brief Receive and process messages in a separate thread.
When an object of this class is created, the message loop can be started
diff --git a/docs/user/app/Message.dox b/docs/user/app/Message.dox
index e7ea4e5..392f7c1 100644
--- a/docs/user/app/Message.dox
+++ b/docs/user/app/Message.dox
@@ -92,7 +92,7 @@
/*!
\class BMessage
\ingroup app
- \ingroup libbe
+ \ingroup libroot
\brief A container that can be send and received using the Haiku
messaging
subsystem.
diff --git a/docs/user/app/MessageFilter.dox b/docs/user/app/MessageFilter.dox
index 4d517f8..5360db0 100644
--- a/docs/user/app/MessageFilter.dox
+++ b/docs/user/app/MessageFilter.dox
@@ -143,7 +143,7 @@
/*!
\class BMessageFilter
\ingroup app
- \ingroup libbe
+ \ingroup libroot
\brief Describes a message filter for BLooper and BHandler.
Objects of this class serve as a description of properties that incoming
@@ -334,4 +334,3 @@ looper->AddCommonFilter(filter);
\fn BLooper *BMessageFilter::Looper() const
\brief Return the looper this filter is associated with.
*/
-
diff --git a/docs/user/app/MessageQueue.dox b/docs/user/app/MessageQueue.dox
index c02de9e..5b0f71c 100644
--- a/docs/user/app/MessageQueue.dox
+++ b/docs/user/app/MessageQueue.dox
@@ -21,17 +21,18 @@
/*!
\class BMessageQueue
\ingroup app
+ \ingroup libroot
\brief A container that maintains a queue of messages.
-
+
This class is used by BLooper to maintain a queue of messages that need
to
be processed. This class has been designed as a first in, first out
container.
-
+
The default message handling of a BLooper probably suffices for most
uses,
but if you want more control, you can perform operations using the
methods
of this class. Use BLooper::MessageQueue() to retrieve the specific
BMessageQueue instance.
-
+
Note that you are encouraged to make sure that whichever operation you
perform, that you only do this after the object has been locked (see
Lock()). The most important method, NextMessage() will fail if you have
not
@@ -67,7 +68,7 @@
The message has to be allocated on the heap with \c new, because the
queue
claims ownership of the message. Messages that were constructed on the
stack will corrupt the queue.
-
+
Because a BMessageQueue claims ownership of the \a message, it is
important
that the message does not belong to another BMessageQueue.
*/
@@ -76,7 +77,7 @@
/*!
\fn void BMessageQueue::RemoveMessage(BMessage* message)
\brief Remove a \a message from the queue.
-
+
If the \a message is indeed associated with this queue, it is removed
from
it. This effectively means that you regain ownership of the message.
*/
@@ -97,9 +98,9 @@
/*!
\fn BMessage *BMessageQueue::FindMessage(int32 index) const
\brief Retrieve the message at the \a index of this queue.
-
+
\param index A zero-based index of the message you want to retrieve.
-
+
\return A pointer to a message, or \c NULL if the \a index is out of
bounds.
\see FindMessage(uint32, int32) for a variant that takes a specific \c
what
@@ -114,7 +115,7 @@
\param index A zero-based index of the message you want to retrieve.
\param what The \a what code of the message.
-
+
\return A pointer to a message, or \c NULL if there is no message at the
\a index with that \a what constant, or if the \a index is out
of
bounds.
@@ -124,7 +125,7 @@
/*!
\fn bool BMessageQueue::Lock()
\brief Lock the queue so no other thread can perform operations on it.
-
+
\see Unlock()
*/
@@ -132,7 +133,7 @@
/*!
\fn void BMessageQueue::Unlock()
\brief Unlock the queue after a Lock() request.
-
+
\see Lock()
*/
@@ -148,10 +149,10 @@
/*!
\fn BMessage *BMessageQueue::NextMessage()
\brief Remove the first BMessage on the queue and return it to the
caller.
-
+
After calling this method, you get the ownership of the message, so make
sure it is deleted after you are done.
-
+
\return A pointer to a message, or \c NULL if the queue is empty, or the
object has not been properly locked.
\see Lock()
diff --git a/docs/user/support/Archivable.dox b/docs/user/support/Archivable.dox
index 2a7a328..51de3b2 100644
--- a/docs/user/support/Archivable.dox
+++ b/docs/user/support/Archivable.dox
@@ -19,7 +19,7 @@
/*!
\file Archivable.h
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Provides the BArchivable interface and declares the BArchiver and
BUnarchiver classes.
*/
@@ -28,7 +28,7 @@
/*!
\class BArchivable
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Interface for objects that can be archived into a BMessage.
BArchivable provides an interface for objects that can be put into
message
diff --git a/docs/user/support/Archiver.dox b/docs/user/support/Archiver.dox
index 0c2532b..8fdeba8 100644
--- a/docs/user/support/Archiver.dox
+++ b/docs/user/support/Archiver.dox
@@ -14,7 +14,7 @@
/*!
\file Archivable.h
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Contains BArchiver class.
*/
@@ -22,7 +22,7 @@
/*!
\class BArchiver
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief A class that simplifies the archiving of complicated BArchivable
hierarchies.
diff --git a/docs/user/support/Autolock.dox b/docs/user/support/Autolock.dox
index ad6e27f..318d45f 100644
--- a/docs/user/support/Autolock.dox
+++ b/docs/user/support/Autolock.dox
@@ -13,7 +13,7 @@
/*!
\file Autolock.h
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Implements a handy locking utility.
*/
@@ -21,7 +21,7 @@
/*!
\class BAutolock
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Convenient utility to make parts of your code thread-safe easily.
The autolocker uses a BLooper or a BLocker in order to protect a part
diff --git a/docs/user/support/Beep.dox b/docs/user/support/Beep.dox
index fa5124c..e0d151f 100644
--- a/docs/user/support/Beep.dox
+++ b/docs/user/support/Beep.dox
@@ -19,7 +19,7 @@
/*!
\file Beep.h
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Functions to generate sounds from the computer.
*/
diff --git a/docs/user/support/BlockCache.dox b/docs/user/support/BlockCache.dox
index 44ff4cf..f32ab9a 100644
--- a/docs/user/support/BlockCache.dox
+++ b/docs/user/support/BlockCache.dox
@@ -18,7 +18,7 @@
/*!
\file BlockCache.h
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Implements a mechanism to store and retrieve memory blocks.
*/
@@ -40,16 +40,16 @@
/*!
\class BBlockCache
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief A class that creates and maintains a pool of memory blocks.
-
+
In some performance critical code there might come a time where you
require
a lot of little blocks of memory that you want to access and dispose of
continuously. Since allocating and freeing memory are 'expensive'
operations, it is better to have a pool of memory blocks at your
disposal.
Luckily, the Haiku API provides a class that will act as the
administrator
of your memory pool, so you will not have to reinvent the wheel every
time.
-
+
The principle is easy. The constructor takes the number of blocks you
want to create beforehand, the size of the blocks, and the method of
allocation. This can either be #B_OBJECT_CACHE or #B_MALLOC_CACHE.
@@ -57,14 +57,14 @@
one uses \c malloc() and \c free(). Unless you have specific demands on
performance or you want to take care of freeing the objects yourself,
either
way works fine.
-
+
As soon as you have the memory pool, you can Get() blocks. If the
pre-allocated memory blocks run out, BBlockCache will allocate new
ones, so
you will not have to worry about availability. As soon as you are done
you
can Save() the memory back into the pool. BBlockCache will make sure
that no
more blocks will be saved than the initial number you requested when you
created the object, so be aware of that.
-
+
As soon as you got a pointer from the Get() method, you own that block
of
memory; this means that you have the liberty to dispose of it yourself.
It
also means that when you delete your BBlockCache instance, any blocks of
@@ -75,7 +75,7 @@
note that it defeats the purpose of this class if your are going to
free all
the objects yourself since it basically means that when the pool runs
out,
Get() will be allocating the objects by itself.
-
+
\note BBlockCache is thread-safe.
*/
@@ -84,7 +84,7 @@
\fn BBlockCache::BBlockCache(uint32 blockCount, size_t blockSize, uint32
allocationType)
\brief Allocate a new memory pool.
-
+
\param blockCount The number of free memory blocks you want to allocate
initially. This number is also used as the maximum number of
free blocks
that will be kept.
@@ -97,7 +97,7 @@
/*!
\fn BBlockCache::~BBlockCache()
\brief Destroy the empty blocks in the free list.
-
+
Note that the blocks you checked out with Get() and not checked back in
with
Save() will not be freed, since ownership belongs to you. Make sure you
clean up after yourself.
@@ -107,12 +107,12 @@
/*!
\fn void *BBlockCache::Get(size_t blockSize)
\brief Get a block from the pool of free blocks.
-
+
If the pool runs out of free blocks, a new one will be allocated. Please
note that if the size given in the \c blockSize parameter is different
from
the size given in the constructor, a new block of memory will be
created.
Only sizes that match the blocks in the memory pool will come from the
pool.
-
+
\param blockSize The required size of the memory block.
\return Returns a pointer to a memory block, or \c NULL if locking the
object failed.
@@ -122,12 +122,12 @@
/*!
\fn void BBlockCache::Save(void *pointer, size_t blockSize)
\brief Save a block of memory to the memory pool.
-
+
The block of memory will only be added to the pool if the \c blockSize
is
equal to the size the object was created with and if the maximum number
of
free blocks in the list will not be exceeded. If not, the memory will be
freed.
-
+
Note that it is perfectly valid to pass objects other than those you got
from Get(), but please note that the way it was created conforms to the
way
memory is allocated and freed in this pool. Therefore, only feed blocks
that
diff --git a/docs/user/support/BufferIO.dox b/docs/user/support/BufferIO.dox
index 81e2358..3f05e6c 100644
--- a/docs/user/support/BufferIO.dox
+++ b/docs/user/support/BufferIO.dox
@@ -15,7 +15,7 @@
/*!
\file BufferIO.h
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Provides the BBufferIO class.
*/
@@ -23,9 +23,8 @@
/*!
\class BBufferIO
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief A buffered adapter for BPositionIO objects.
- \author Stefano Ceccherini \<burton666@xxxxxxxxxxx\>
This class differs from other classes derived from BPositionIO in a
sense
that it does not actually provide an actual entity to be read or
written
diff --git a/docs/user/support/DataIO.dox b/docs/user/support/DataIO.dox
index bc6e61c..91fe6f2 100644
--- a/docs/user/support/DataIO.dox
+++ b/docs/user/support/DataIO.dox
@@ -15,7 +15,7 @@
/*!
\file DataIO.h
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Defines abstract BDataIO and BPositionIO and the derived
BMallocIO and BMemoryIO classes.
Pure virtual BDataIO and BPositioIO classes provide
@@ -32,7 +32,7 @@
/*!
\class BDataIO
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Abstract interface for objects that provide read and write
access to
data.
diff --git a/docs/user/support/Flattenable.dox
b/docs/user/support/Flattenable.dox
index eaa4ba5..d582651 100644
--- a/docs/user/support/Flattenable.dox
+++ b/docs/user/support/Flattenable.dox
@@ -14,7 +14,7 @@
/*!
\file Flattenable.h
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Provides the BFlattenable interface
*/
@@ -22,7 +22,7 @@
/*!
\class BFlattenable
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Interface for classes that can flatten and unflatten themselves
to
a stream of bytes.
diff --git a/docs/user/support/List.dox b/docs/user/support/List.dox
index 2773cb4..5158acf 100644
--- a/docs/user/support/List.dox
+++ b/docs/user/support/List.dox
@@ -19,7 +19,7 @@
/*!
\file List.h
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Defines the BList class.
*/
@@ -27,7 +27,7 @@
/*!
\class BList
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief An ordered container that is designed to hold generic \c void*
objects.
diff --git a/docs/user/support/Locker.dox b/docs/user/support/Locker.dox
index 5bbe972..396adf0 100644
--- a/docs/user/support/Locker.dox
+++ b/docs/user/support/Locker.dox
@@ -13,14 +13,15 @@
/*!
\file Locker.h
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Provides locking class BLocker.
*/
+
/*!
\class BLocker
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Semaphore-type class for thread safety.
The BLocker interface is not merely a wrapper around a semaphore, but it
@@ -29,10 +30,10 @@
because before it uses the internal semaphore, it first checks against a
variable that is only operated on with atomic operations. Setting a
variable
is a lot more efficient than acquiring a semaphore, thus this type of
locking
- is much prefered.
+ is much preferred.
It basically works as follows. Whenever you newly created BLocker object
- recieves a locking request, it atomically sets the benaphore variable
to
+ receives a locking request, it atomically sets the benaphore variable to
\c 1. Then only additional calls from different threads will utilize the
semaphore. You can imagine that in many cases where you protect
of data that \em might be accessed by two or more concurrent threads,
but
@@ -42,7 +43,7 @@
The other feature of BLocker that improves basic semaphore handling is
that
it allows for recursive locks. The following piece of code works with a
BLocker, but block inevitably with a semaphore. Let's pretend I call
- \c Water():
+ \c Water():
\code
status_t
@@ -76,12 +77,13 @@ Flower::Water(int amount)
pair every Lock() with an Unlock() though, or you'll create a deadlock.
*/
+
/*!
\fn BLocker::BLocker()
\brief Constructor.
- Create a new BLocker with the default name of <tt>some BLocker</tt>.
This
- BLocker will use the benaphore-style locking.
+ Create a new BLocker with the default name of some BLocker. This
+ BLocker will use the benaphore-style locking.
\note For debugging purposes, it's extremely convenient to actually
give a
name to the object. In case of a deadlock, it's easier to track down which
@@ -90,6 +92,7 @@ Flower::Water(int amount)
\see BLocker(const char* name, bool benaphoreStyle) for all the options.
*/
+
/*!
\fn BLocker::BLocker(const char* name)
\brief Constructor.
@@ -104,6 +107,7 @@ Flower::Water(int amount)
\see BLocker(const char* name, bool benaphoreStyle) for all the options.
*/
+
/*!
\fn BLocker::BLocker(bool benaphoreStyle)
\brief Constructor.
@@ -123,6 +127,7 @@ Flower::Water(int amount)
to set a name.
*/
+
/*!
\fn BLocker::BLocker(const char* name, bool benaphoreStyle)
\brief Constructor.
@@ -137,20 +142,22 @@ Flower::Water(int amount)
for its functioning.
*/
+
/*!
\fn virtual BLocker::~BLocker()
\brief Destructor.
Release the internal semaphore. Because of this, any pending Lock()
calls
from other threads be cancelled. The return code will be \c false for
- those calls.
+ those calls.
*/
+
/*!
\fn bool BLocker::Lock()
\brief Add a lock request and block on it until we get it.
- \retval true Lock acquired succesfully.
+ \retval true Lock acquired successfully.
\retval false Failed to acquire the lock. Most probable cause is that
the
object is deleted. This frees the semaphore and
releases the
pending Lock() requests.
@@ -158,6 +165,7 @@ Flower::Water(int amount)
\see LockWithTimeout(bigtime_t timeout), Unlock()
*/
+
/*!
\fn status_t BLocker::LockWithTimeout(bigtime_t timeout)
\brief Add a lock request and block until we get it or until it times
out.
@@ -168,17 +176,20 @@ Flower::Water(int amount)
\see Lock(), Unlock()
*/
+
/*!
\fn void BLocker::Unlock(void)
\brief Release the lock that's currently held.
*/
+
/*!
\fn thread_id BLocker::LockingThread(void) const
\brief Return the \c thread_id of the thread that's currently holding
the
lock.
*/
+
/*!
\fn bool BLocker::IsLocked(void) const
\brief Check if the calling thread is actually holding the lock.
@@ -188,16 +199,19 @@ Flower::Water(int amount)
\retval false The object is unlocked or the lock is held by another
thread.
*/
+
/*!
\fn int32 BLocker::CountLocks(void) const
\brief Return the number of recursive locks that are currently held.
*/
+
/*!
\fn nt32 BLocker::CountLockRequests(void) const
\brief Return the number of threads with a pending lock request.
*/
+
/*!
\fn sem_id BLocker::Sem(void) const
\brief Return the sem_id of the semaphore this object holds.
diff --git a/docs/user/support/String.dox b/docs/user/support/String.dox
index c6cebbc..7da1856 100644
--- a/docs/user/support/String.dox
+++ b/docs/user/support/String.dox
@@ -24,7 +24,7 @@
/*!
\class BString String.h
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief String class supporting common string operations.
BString is a string allocation and manipulation class. The object
diff --git a/docs/user/support/SupportDefs.dox
b/docs/user/support/SupportDefs.dox
index 8c29d42..655fa3d 100644
--- a/docs/user/support/SupportDefs.dox
+++ b/docs/user/support/SupportDefs.dox
@@ -13,7 +13,7 @@
/*!
\file SupportDefs.h
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief Defines basic types and definitions for the Haiku API.
*/
diff --git a/docs/user/support/Unarchiver.dox b/docs/user/support/Unarchiver.dox
index 983d2dc..2840098 100644
--- a/docs/user/support/Unarchiver.dox
+++ b/docs/user/support/Unarchiver.dox
@@ -23,7 +23,7 @@
/*!
\class BUnarchiver
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief A class that simplifies the unarchiving of complicated
BArchivable
hierarchies.
diff --git a/docs/user/support/stopwatch.dox b/docs/user/support/stopwatch.dox
index 2977cd5..b52fbd4 100644
--- a/docs/user/support/stopwatch.dox
+++ b/docs/user/support/stopwatch.dox
@@ -22,7 +22,7 @@
/*!
\class BStopWatch
\ingroup support
- \ingroup libbe
+ \ingroup libroot
\brief A timer class.
This class provides method to time events. The interface is designed to
Other related posts:
