Skip to content

Commit

Permalink
fix doxygen comments
Browse files Browse the repository at this point in the history
  • Loading branch information
@carltimmer
carltimmer committed Sep 26, 2024
1 parent c30c22b commit 6ef6f93
Show file tree
Hide file tree
Showing 24 changed files with 548 additions and 536 deletions.
36 changes: 0 additions & 36 deletions src/libsrc++/BankHeader.cpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,30 +24,10 @@ namespace evio {
BaseStructureHeader(tag, dataType, num) {length = 1;}


/**
* Get the length of the structure's data in 32 bit ints (not counting the header words).
* @return Get the length of the structure's data in 32 bit ints (not counting the header words).
*/
uint32_t BankHeader::getDataLength() {return length - 1;}


/**
* Get the length of the structure's header in ints. This includes the first header word itself
* (which contains the length) and in the case of banks, it also includes the second header word.
* @return Get the length of the structure's header in ints.
*/
uint32_t BankHeader::getHeaderLength() {return 2;}


/**
* Write myself out as evio format data
* into the given byte array in the specified byte order.
*
* @param dest array into which evio data is written (destination).
* @param order byte order in which to write the data.
* @return the number of bytes written, which for a BankHeader is 8.
* @throws EvioException if destination array too small to hold data.
*/
size_t BankHeader::write(uint8_t *dest, ByteOrder const & order) {
// length first
Util::toBytes(length, order, dest);
Expand All @@ -57,26 +37,10 @@ namespace evio {
return 8;
}


/**
* Write myself out a byte buffer.
* This write is relative - i.e., it uses the current position of the buffer.
*
* @param byteBuffer the byteBuffer to write to.
* @return the number of bytes written, which for a BankHeader is 8.
*/
size_t BankHeader::write(std::shared_ptr<ByteBuffer> byteBuffer) {
return write(*(byteBuffer.get()));
}


/**
* Write myself out a byte buffer.
* This write is relative - i.e., it uses the current position of the buffer.
*
* @param dest the byteBuffer to write to.
* @return the number of bytes written, which for a BankHeader is 8.
*/
size_t BankHeader::write(ByteBuffer & dest) {
dest.putInt(length);

Expand Down
83 changes: 59 additions & 24 deletions src/libsrc++/BaseStructure.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,30 +46,29 @@
namespace evio {


/////////////////////////////////// DEPTH FIRST ITERATOR

/** Depth first iterator. */
template<typename R>
class nodeIterator {

// iterator of vector contained shared pointers to node's children
/** Iterator of vector contained shared pointers to node's children. */
typedef typename std::vector<R>::iterator KidIter;

protected:

// Stack of pair containing 2 iterators, each iterating over vector
// of node's children (shared pts).
// In each pair, first is current iterator, second is end iterator.
/** Stack of pair containing 2 iterators, each iterating over vector
* of node's children (shared pts).
* In each pair, first is current iterator, second is end iterator. */
std::stack<std::pair<KidIter, KidIter>> stack;

// Where we are now in the tree
/** Where we are now in the tree. */
R currentNode;

// Is this the end iterator?
/** Is this the end iterator? */
bool isEnd;

public:

// Copy shared pointer arg
/** Constructor that copies shared pointer arg. */
explicit nodeIterator(R &node, bool isEnd) : currentNode(node), isEnd(isEnd) {
// store current-element and end of vector in pair
if (!node->children.empty()) {
Expand All @@ -78,8 +77,10 @@ namespace evio {
}
}

/** Dereference operator. */
R operator*() const { return currentNode; }

/** Equal operator. */
bool operator==(const nodeIterator &other) const {
// Identify end iterator
if (isEnd && other.isEnd) {
Expand All @@ -88,6 +89,7 @@ namespace evio {
return this == &other;
}

/** Not equal operator. */
bool operator!=(const nodeIterator &other) const {
// Identify end iterator
if (isEnd && other.isEnd) {
Expand All @@ -96,9 +98,13 @@ namespace evio {
return this != &other;
}

/**
* Is this the end of the iterator?
* @return true if end of iterator.
*/
bool isEndIter() {return isEnd;}

// post increment gets ignored arg of 0 to distinguish from pre, A++
/** Post increment operator gets ignored arg of 0 to distinguish from pre, A++. */
const nodeIterator operator++(int) {

if (isEnd) return *this;
Expand Down Expand Up @@ -142,7 +148,7 @@ namespace evio {
}


// pre increment, ++A
/** Pre increment operator, ++A. */
const nodeIterator &operator++() {

if (isEnd) return *this;
Expand Down Expand Up @@ -183,33 +189,32 @@ namespace evio {
};


/////////////////////////////////// BREADTH FIRST ITERATOR

/** Breadth first iterator. */
template<typename R>
class nodeBreadthIterator {

protected:

// iterator of vector contained shared pointers to node's children
/** iterator of vector contained shared pointers to node's children. */
typedef typename std::vector<R>::iterator KidIter;

// Stack of iterators of vector of shared pointers.
// Queue of iterators of vector of shared pointers.
// Each vector contains the children of a node,
// thus each iterator gives all a node's kids.

// Stack of iterators over node's children.
// In each pair, first is current iterator, second is end
/** Queue of iterators over node's children.
* In each pair, first is current iterator, second is end. */
std::queue<std::pair<KidIter, KidIter>> que;

// Where we are now in the tree
/** Where we are now in the tree. */
R currentNode;

// Is this the end iterator?
/** Is this the end iterator? */
bool isEnd;

public:

// Copy shared pointer arg
/** Constructor that copies shared pointer arg. */
nodeBreadthIterator(R & node, bool isEnd) : currentNode(node), isEnd(isEnd) {
// store current-element and end of vector in pair
if (!node->children.empty()) {
Expand All @@ -218,27 +223,34 @@ namespace evio {
}
}

/** Dereference operator. */
R operator*() const { return currentNode; }

/** Equal operator. */
bool operator==(const nodeBreadthIterator &other) const {
if (isEnd && other.isEnd) {
return true;
}
return this == &other;
}

/** Not equal operator. */
bool operator!=(const nodeBreadthIterator &other) const {
if (isEnd && other.isEnd) {
return false;
}
return this != &other;
}

/**
* Is this the end of the iterator?
* @return true if end of iterator.
*/
bool isEndIter() {return isEnd;}

// TODO: How does one handle going too far???

// post increment gets ignored arg of 0 to distinguish from pre, A++
/** Post increment operator gets ignored arg of 0 to distinguish from pre, A++. */
nodeBreadthIterator operator++(int) {

if (isEnd) {
Expand Down Expand Up @@ -284,7 +296,7 @@ namespace evio {
}


// pre increment, ++A
/** Pre increment operator, ++A. */
nodeBreadthIterator operator++() {

if (isEnd) {
Expand Down Expand Up @@ -358,16 +370,23 @@ namespace evio {

public:

// For defining our own iterator
/** For our own iterator, define size type. */
typedef size_t size_type;
/** For our own iterator, define pointer difference type. */
typedef std::ptrdiff_t difference_type;
/** For our own iterator, define iterator category type. */
typedef std::input_iterator_tag iterator_category;

/** For our own iterator, define value type. */
typedef std::shared_ptr<BaseStructure> value_type;
/** For our own iterator, define reference type. */
typedef std::shared_ptr<BaseStructure> reference;
/** For our own iterator, define pointer type. */
typedef std::shared_ptr<BaseStructure> pointer;

/** Depth first iterator for this element in a tree. */
typedef nodeIterator<std::shared_ptr<BaseStructure>> iterator;
/** Breadth first iterator for this element in a tree. */
typedef nodeBreadthIterator<std::shared_ptr<BaseStructure>> breadth_iterator;

friend class nodeIterator<std::shared_ptr<BaseStructure>>;
Expand Down Expand Up @@ -413,8 +432,20 @@ namespace evio {
bool allowsChildren = true;

public:

/**
* This methods calls shared_from_this() to obtain a new std::shared_ptr that
* shares ownership of the current object (this).
* @return a new std::shared_ptr that shares ownership of the current object.
*/
std::shared_ptr<BaseStructure> getThis() {return shared_from_this();}

/**
* This methods calls shared_from_this() to obtain a new std::shared_ptr that
* shares ownership of the current object (this). However that shared pointer
* cannot be used to change the object.
* @return a new std::shared_ptr that shares ownership of the current object
* which is treated as read-only.
*/
std::shared_ptr<const BaseStructure> getThisConst() const {return shared_from_this();}

protected:
Expand Down Expand Up @@ -641,6 +672,10 @@ namespace evio {

void transform(std::shared_ptr<BaseStructure> structure);

/**
* Get the type of structure this object represents (bank, seg, tagseg, or unknown).
* @return type of structure this object represents.
*/
virtual StructureType getStructureType() const {return StructureType::STRUCT_UNKNOWN32;};

ByteOrder getByteOrder();
Expand Down
44 changes: 44 additions & 0 deletions src/libsrc++/BaseStructureHeader.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,12 +101,56 @@ namespace evio {
uint16_t getTag() const;
void setTag(uint16_t tag);

/**
* Get the length of the structure's data in 32 bit ints (not counting the header words).
* @return Get the length of the structure's data in 32 bit ints (not counting the header words).
*/
virtual uint32_t getDataLength() {return 0;};

/**
* Get the length of the structure's header in ints. This includes the first header word itself
* (which contains the length) and in the case of banks, it also includes the second header word.
* @return length of the structure's header in ints (2 for banks, 1 for segments and tagsegments).
*/
virtual uint32_t getHeaderLength() {return 0;};

/**
* Obtain a string representation of the base structure header.
* @return a string representation of the base structure header.
*/
virtual std::string toString() {return "BaseStructureHeader";};


/**
* Write myself out into a byte buffer.
* This write is relative - i.e., it uses the current position of the buffer.
*
* @param dest the byteBuffer to write to.
* @return the number of bytes written, which for a BankHeader is 8 and for
* a SegmentHeader or TagSegmentHeader is 4.
*/
virtual size_t write(std::shared_ptr<ByteBuffer> dest) {return 0;}

/**
* Write myself out into a byte buffer.
* This write is relative - i.e., it uses the current position of the buffer.
*
* @param dest the byteBuffer to write to.
* @return the number of bytes written, which for a BankHeader is 8 and for
* a SegmentHeader or TagSegmentHeader is 4.
*/
virtual size_t write(ByteBuffer & dest) {return 0;};

/**
* Write myself out as evio format data
* into the given byte array in the specified byte order.
*
* @param dest array into which evio data is written (destination).
* @param order byte order in which to write the data.
* @return the number of bytes written, which for a BankHeader is 8 and for
* a SegmentHeader or TagSegmentHeader is 4.
* @throws EvioException if destination array too small to hold data.
*/
virtual size_t write(uint8_t *dest, ByteOrder const & order) {return 0;};

};
Expand Down
3 changes: 1 addition & 2 deletions src/libsrc++/BlockHeaderV4.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,6 @@ namespace evio {
* | Magic Int |
* |_____________________________________|
*
* The following bit #s start with 0.
*
* Block Length = number of ints in block (including this one).
* Block Number = id number (starting at 1)
Expand All @@ -79,7 +78,7 @@ namespace evio {
*
*
*
* Bit info has the following bits defined (bit #s start with 0):
* Bit info has the following bits defined (bit numbers start with 0):
* Bit 8 = true if dictionary is included (relevant for first block only)
*
* Bit 9 = true if this block is the last block in file or network transmission
Expand Down
Loading

0 comments on commit 6ef6f93

Please sign in to comment.