Commit 1508fe48 authored by David Thompson's avatar David Thompson

Documentation improvements.

parent ffb881e0
......@@ -293,7 +293,7 @@ IDL_PROPERTY_SUPPORT = YES
# member in the group (if any) for the other members of the group. By default
# all members of a group must be documented explicitly.
DISTRIBUTE_GROUP_DOC = NO
DISTRIBUTE_GROUP_DOC = YES
# Set the SUBGROUPING tag to YES (the default) to allow class member groups of
# the same type (for instance a group of public functions) to be put as a
......@@ -675,6 +675,7 @@ INPUT = \
"@SMTK_SOURCE_DIR@/smtk/model/testing" \
"@SMTK_SOURCE_DIR@/smtk/Qt" \
"@SMTK_SOURCE_DIR@/smtk/util" \
"@SMTK_SOURCE_DIR@/smtk/util/Testing" \
"@SMTK_SOURCE_DIR@/smtk/view" \
"@SMTK_SOURCE_DIR@/smtk/vtk" \
"@SMTK_BINARY_DIR@/smtk" \
......@@ -730,7 +731,7 @@ EXCLUDE_SYMLINKS = NO
# against the file with absolute path, so to exclude all test directories
# for example use the pattern */test/*
EXCLUDE_PATTERNS = "*Wrapper*"
EXCLUDE_PATTERNS = "*Wrapper*" "moc_*"
# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
# (namespaces, classes, functions, etc.) that should be excluded from the
......
......@@ -8,6 +8,9 @@
namespace smtk {
namespace model {
/**\brief Present the contents of an smtk::model::Storage instance via QEntityItemModel.
*
*/
class QTSMTK_EXPORT QEntityItemDelegate : public QStyledItemDelegate
{
Q_OBJECT
......
......@@ -9,7 +9,10 @@ class QLineEdit;
namespace smtk {
namespace model {
class QEntityItemEditor : public QWidget
/**\brief Allow user edits to an smtk::model::Storage instance via QEntityItemModel.
*
*/
class QTSMTK_EXPORT QEntityItemEditor : public QWidget
{
Q_OBJECT
public:
......
......@@ -12,6 +12,9 @@
namespace smtk {
namespace model {
/**\brief Adapt an smtk::model::Storage instance into a hierarchical Qt model.
*
*/
class QTSMTK_EXPORT QEntityItemModel : public QAbstractItemModel
{
Q_OBJECT
......
......@@ -57,7 +57,7 @@ std::string AbbreviationForArrangementKind(ArrangementKind k)
return ArrangementKindAbbr[k];
}
/**\brief Methods to construct arrangement records.
/** @name Methods to construct arrangement records.
*
* These should be preferred to manual construction of arrangements so that
* conventions can be changed in the future.
......@@ -73,7 +73,7 @@ std::string AbbreviationForArrangementKind(ArrangementKind k)
* index and sense in the function call -- this does not necessarily reflect
* their order in the arrangement).
*/
//@{
///@{
/**\brief Construct an arrangement record to add to a cell, indicating a use of that cell.
*
* The \a relationIdx is the offset in the Entity::relations() array of the USE_ENTITY.
......@@ -144,7 +144,68 @@ Arrangement Arrangement::ShellHasUseWithIndexRange(int relationBegin, int relati
}
return result;
}
//@}
///@}
/** @name Methods to interpret arrangements.
*
* Use these methods to obtain integers assocated with a semantic meaning
* from the arrangement vector.
* If a vector is not sized properly, these methods will return false.
*/
///@{
bool Arrangement::IndexAndSenseFromCellHasUse(int& relationIdx, int& sense)
{
if (this->m_details.size() != 2)
{
return false;
}
relationIdx = this->m_details[0];
sense = this->m_details[1];
return true;
}
bool Arrangement::IndexAndSenseFromUseHasCell(int& relationIdx, int& sense)
{
if (this->m_details.size() != 2)
{
return false;
}
relationIdx = this->m_details[0];
sense = this->m_details[1];
return true;
}
bool Arrangement::IndexFromCellEmbeddedInEntity(int& relationIdx)
{
if (this->m_details.size() != 1)
{
return false;
}
relationIdx = this->m_details[0];
return true;
}
bool Arrangement::IndexFromShellHasCell(int& relationIdx)
{
if (this->m_details.size() != 1)
{
return false;
}
relationIdx = this->m_details[0];
return true;
}
bool Arrangement::IndexRangeFromShellHasUse(int& relationBegin, int& relationEnd)
{
if (this->m_details.size() != 2)
{
return false;
}
relationBegin = this->m_details[0];
relationEnd = this->m_details[1];
return true;
}
///@}
} //namespace model
} // namespace smtk
......@@ -59,10 +59,14 @@ SMTKCORE_EXPORT std::string AbbreviationForArrangementKind(ArrangementKind k);
class SMTKCORE_EXPORT Arrangement
{
public:
///@{
/**\brief Access to the integer vector defining an arrangement.
*/
std::vector<int>& details()
{ return this->m_details; }
std::vector<int> const& details() const
{ return this->m_details; }
///@}
static Arrangement CellHasUseWithIndexAndSense(int relationIdx, int sense);
static Arrangement UseHasCellWithIndexAndSense(int relationIdx, int sense);
......@@ -70,6 +74,12 @@ public:
static Arrangement ShellHasCellWithIndex(int relationIdx);
static Arrangement ShellHasUseWithIndexRange(int relationBegin, int relationEnd);
bool IndexAndSenseFromCellHasUse(int& relationIdx, int& sense);
bool IndexAndSenseFromUseHasCell(int& relationIdx, int& sense);
bool IndexFromCellEmbeddedInEntity(int& relationIdx);
bool IndexFromShellHasCell(int& relationIdx);
bool IndexRangeFromShellHasUse(int& relationBegin, int& relationEnd);
protected:
std::vector<int> m_details; // Kind-dependent specification of the arrangement.
};
......
......@@ -220,7 +220,7 @@ std::string BRepModel::name(const UUID& ofEntity) const
*
* \sa HigherDimensionalBoundaries
*/
UUIDs BRepModel::bordantEntities(const UUID& ofEntity, int ofDimension)
UUIDs BRepModel::bordantEntities(const smtk::util::UUID& ofEntity, int ofDimension)
{
UUIDs result;
UUIDsToEntities::iterator it = this->m_topology->find(ofEntity);
......@@ -255,7 +255,7 @@ UUIDs BRepModel::bordantEntities(const UUID& ofEntity, int ofDimension)
*
* \sa HigherDimensionalBoundaries
*/
UUIDs BRepModel::bordantEntities(const UUIDs& ofEntities, int ofDimension)
UUIDs BRepModel::bordantEntities(const smtk::util::UUIDs& ofEntities, int ofDimension)
{
UUIDs result;
std::insert_iterator<UUIDs> inserter(result, result.begin());
......@@ -271,7 +271,7 @@ UUIDs BRepModel::bordantEntities(const UUIDs& ofEntities, int ofDimension)
*
* \sa LowerDimensionalBoundaries
*/
UUIDs BRepModel::boundaryEntities(const UUID& ofEntity, int ofDimension)
UUIDs BRepModel::boundaryEntities(const smtk::util::UUID& ofEntity, int ofDimension)
{
UUIDs result;
UUIDsToEntities::iterator it = this->m_topology->find(ofEntity);
......@@ -306,7 +306,7 @@ UUIDs BRepModel::boundaryEntities(const UUID& ofEntity, int ofDimension)
*
* \sa LowerDimensionalBoundaries
*/
UUIDs BRepModel::boundaryEntities(const UUIDs& ofEntities, int ofDimension)
UUIDs BRepModel::boundaryEntities(const smtk::util::UUIDs& ofEntities, int ofDimension)
{
UUIDs result;
std::insert_iterator<UUIDs> inserter(result, result.begin());
......@@ -528,6 +528,10 @@ void BRepModel::addToGroup(const smtk::util::UUID& groupId, const UUIDs& uids)
this->insertEntityReferences(result);
}
/** @name Model property accessors.
*
*/
///@{
void BRepModel::setFloatProperty(
const smtk::util::UUID& entity,
const std::string& propName,
......@@ -785,6 +789,7 @@ UUIDWithIntegerProperties BRepModel::integerPropertiesForEntity(const smtk::util
{
return this->m_integerData->find(entity);
}
///@}
/// Add a vertex to storage (without any relationships)
smtk::util::UUID BRepModel::addVertex()
......
......@@ -6,6 +6,12 @@
namespace smtk {
namespace model {
/**\brief Report all of the "use" records associated with the cell.
*
* The uses can be used to discover higher-dimensional cells that
* this cell borders.
* Each sense of a cell has its own use.
*/
UseEntities CellEntity::uses() const
{
UseEntities result;
......
......@@ -7,6 +7,9 @@
namespace smtk {
namespace model {
/**\brief A cursor subclass with methods specific to cell entities.
*
*/
class SMTKCORE_EXPORT CellEntity : public Cursor
{
public:
......
......@@ -6,6 +6,9 @@
namespace smtk {
namespace model {
/**\brief Describe a list of entities for user presentation.
*
*/
class EntityListPhrase : public DescriptivePhrase
{
public:
......
......@@ -39,6 +39,29 @@ Cursor EntityPhrase::relatedEntity() const
bool EntityPhrase::buildSubphrasesInternal()
{
// I. Add arrangement information
ArrangementKind kind;
for (int ikind = 0; ikind < KINDS_OF_ARRANGEMENTS; ++ikind)
{
kind = static_cast<ArrangementKind>(ikind);
int na = this->m_entity.numberOfArrangementsOfKind(kind);
for (int a = 0; a < na; ++a)
{
const Arrangement* arr = this->m_entity.findArrangement(kind, a);
if (!arr->details().empty())
{
CursorArray relations;
arr->relatedEntities(relations);
this->m_subphrases.push_back(
EntityListPhrase::create()->setup(
relations, shared_from_this()));
}
}
}
// II. Add attribute information
// TODO.
// III. Add property information
if (this->m_entity.hasStringProperties())
{ // TODO: If m_entity.stringProperties().size() < N, add PropValuePhrases instead of a list.
this->m_subphrases.push_back(
......
......@@ -6,6 +6,8 @@
namespace smtk {
namespace model {
/**\brief Describe an entity for user presentation.
*/
class EntityPhrase : public DescriptivePhrase
{
public:
......
......@@ -15,6 +15,13 @@ namespace smtk {
class Storage;
/**\brief Export an SMTK model into a JSON-formatted string.
*
* Methods are also provided for creating cJSON nodes representing
* individual records and groups of records from SMTK storage.
* These may be used to provide concise answers to specific queries
* and avoid storing or transmitting a potentially-large string.
*/
class SMTKCORE_EXPORT ExportJSON
{
public:
......
......@@ -13,6 +13,13 @@ namespace smtk {
class Storage;
/**\brief Import an SMTK model from JSON data.
*
* Methods are also provided for importing individual records
* and groups of records directly from cJSON nodes.
* These may be used to update relevant entities without
* storing or transmitting a potentially-large string.
*/
class SMTKCORE_EXPORT ImportJSON
{
public:
......
......@@ -10,6 +10,13 @@
namespace smtk {
namespace model {
/**\brief Describe a list of property (name,value) pairs
* associated with an entity for user presentation.
*
* This enumerates properties of a single primitive storage
* type (e.g. only string properties or only integer properties),
* not all of an entity's properties at once.
*/
class SMTKCORE_EXPORT PropertyListPhrase : public DescriptivePhrase
{
public:
......
......@@ -10,6 +10,9 @@
namespace smtk {
namespace model {
/**\brief Describe the value of a named property for user presentation.
*
*/
class SMTKCORE_EXPORT PropertyValuePhrase : public DescriptivePhrase
{
public:
......
......@@ -12,6 +12,12 @@ typedef std::set<ShellEntity> ShellEntities;
class UseEntity;
typedef std::vector<UseEntity> UseEntities;
/**\brief A cursor subclass with methods specific to shell entities.
*
* A shell is a collection of oriented cell uses that form a
* subset of the boundary of a higher-dimensional parent cell.
* A shell may contain other shells.
*/
class SMTKCORE_EXPORT ShellEntity : public Cursor
{
public:
......
......@@ -18,6 +18,11 @@
namespace smtk {
namespace model {
/**\brief Store information about solid models.
*
* This adds information about arrangements and tessellations
* of entities to its BRepModel base class.
*/
class SMTKCORE_EXPORT Storage : public BRepModel
{
public:
......
......@@ -8,6 +8,9 @@ namespace smtk {
class CellEntity;
/**\brief A cursor subclass that provides methods specific to entity use records.
*
*/
class SMTKCORE_EXPORT UseEntity : public Cursor
{
public:
......
......@@ -8,6 +8,9 @@
namespace smtk {
namespace model {
/**\brief A cursor subclass that provides methods specific to 0-d vertex cells.
*
*/
class SMTKCORE_EXPORT Vertex : public CellEntity
{
public:
......
......@@ -142,12 +142,17 @@ UUIDArray createTet(smtk::model::StoragePtr sm)
return uids;
}
/** Report an integer as a hexadecimal value.
*
* The constant will be zero-padded to a width of 8.
*/
std::ostream& operator << (std::ostream& os, const hexconst& x)
{
os << std::setbase(16) << std::fixed << std::setw(8) << std::setfill('0') << x.m_val;
return os;
}
/// Platform-specific data for measuring elapsed time.
#ifdef SMTK_HAVE_GETTIMEOFDAY
class Timer::Internal
{
......@@ -188,11 +193,17 @@ Timer::~Timer()
delete this->P;
}
/// Mark a time as the start time for reporting elapsed time.
void Timer::mark()
{
this->P->fetch();
}
/** Report the number of seconds since Timer::mark() was last called.
*
* On sane platforms, this will have microsecond precision.
* On Windows, this will have millisecond precision at best.
*/
double Timer::elapsed()
{
Internal other;
......
......@@ -12,6 +12,7 @@ namespace smtk {
smtk::util::UUIDArray createTet(smtk::model::StoragePtr sm);
/// Report an integer as a hexadecimal value.
class hexconst
{
public:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment