Added some documentation

git-svn-id: file:///srv/svn/repos/haiku/trunk/current@648 a95241bf-73f2-0310-859d-f6bbb57e9c96

headers/private/storage/sniffer/Err.h

@@ -15,6 +15,15 @@
 namespace Sniffer {
 
 //! Exception class used by the MIME Sniffer
+/*! Each exception contains an error message, and an byte offset into
+	the original rule that generated the error, for the sake of
+	providing spiffy error messages of the following sort:
+	
+	<code>
+	"1.0 ('abc' & 0xFFAAFFAA)"
+	              ^    Sniffer pattern error: pattern and mask lengths do not match
+	</code>
+*/
 class Err {
 public:
 	Err(const char *msg, const ssize_t pos);
@@ -27,13 +36,13 @@ public:
 	status_t SetTo(const std::string &msg, const ssize_t pos);
 	void Unset();
 	
+	void SetMsg(const char *msg);
+	void SetPos(ssize_t pos);
+
 	const char* Msg() const;
 	ssize_t Pos() const;
 	
 private:
-	friend class Parser;	// So it can update the pos of its out of mem object
-	void SetMsg(const char *msg);
-	void SetPos(ssize_t pos);
 	char *fMsg;
 	ssize_t fPos;
 };

headers/private/storage/sniffer/Expr.h

@@ -13,7 +13,7 @@ class BPositionIO;
 
 namespace Sniffer {
 
-//! Abstract class definining an interface for sniffing BFile objects
+//! Base expression class
 class Expr {
 public:
 	virtual ~Expr() {}

headers/private/storage/sniffer/Pattern.h

@@ -19,7 +19,8 @@ namespace Sniffer {
 
 class Err;
 
-//! Abstract class definining an interface for sniffing BPositionIO objects
+//! A byte string and optional mask to be compared against a data stream.
+/*! The byte string and mask (if supplied) must be of the same length. */
 class Pattern {
 public:
 	Pattern(const char *string, const char *mask = NULL);

headers/private/storage/sniffer/PatternList.h

@@ -20,6 +20,7 @@ namespace Sniffer {
 class Err;
 class Pattern;
 
+//! A list of patterns, all of which are to be searched over the same range.
 class PatternList : public Expr {
 public:
 	PatternList(Range range);

headers/private/storage/sniffer/RPattern.h

@@ -18,7 +18,7 @@ namespace Sniffer {
 class Err;
 class Pattern;
 
-//! Abstract class definining an interface for sniffing BFile objects
+//! A Pattern and a Range, bundled into one.
 class RPattern {
 public:
 	RPattern(Range range, Pattern *pattern);

headers/private/storage/sniffer/RPatternList.h

@@ -19,6 +19,7 @@ namespace Sniffer {
 class Err;	
 class RPattern;
 
+//! A list of patterns, each of which is to be searched over its own specified range.
 class RPatternList : public Expr {
 public:
 	RPatternList();

headers/private/storage/sniffer/Range.h

@@ -15,6 +15,7 @@ namespace Sniffer {
 
 class Err;
 
+//! A range of byte offsets from which to check a pattern against a data stream.
 class Range {
 public:
 	Range(int32 start, int32 end);

src/kits/storage/sniffer/Pattern.cpp

@@ -36,8 +36,6 @@ Pattern::GetErr() const {
 		return NULL;
 	else
 		return new(nothrow) Err(*fErrorMessage);
-//	return fErrorMessage ? NULL : new Err(*fErrorMessage);
-//	return new Err("HEY, FIX THIS CRAP!", -1);
 }
 
 status_t
@@ -66,6 +64,10 @@ Pattern::SetTo(const char *string, const char *mask) {
 	}
 }
 
+/*! \brief Looks for a pattern match in the given data stream, starting from
+	each offset withing the given range. Returns true is a match is found,
+	false if not.
+*/
 bool
 Pattern::Sniff(Range range, BPositionIO *data) const {
 	// If our range contains negative values relative to the end of

src/kits/storage/sniffer/PatternList.cpp

@@ -37,6 +37,9 @@ PatternList::GetErr() const {
 	return fRange.GetErr();
 }
 
+/*! \brief Sniffs the given data stream, searching for a match with
+	any of the list's patterns.
+*/
 bool
 PatternList::Sniff(BPositionIO *data) const {
 	if (InitCheck() != B_OK)

src/kits/storage/sniffer/RPattern.cpp

@@ -51,6 +51,7 @@ RPattern::~RPattern() {
 	delete fPattern;
 }
 
+//! Sniffs the given data stream over the object's range for the object's pattern
 bool
 RPattern::Sniff(BPositionIO *data) const {
 	if (!data || InitCheck() != B_OK)

src/kits/storage/sniffer/RPatternList.cpp

@@ -36,6 +36,10 @@ RPatternList::GetErr() const {
 	return NULL;
 }
 
+/*! Sniffs the given data stream, searching for a match
+	with any of the list's patterns. Each pattern is searched
+	over its own specified range.
+*/
 bool
 RPatternList::Sniff(BPositionIO *data) const {
 	if (InitCheck() != B_OK)