From 1b76b692444fa3017e0337cf337b111edc967ff7 Mon Sep 17 00:00:00 2001 From: danij Date: Thu, 22 Nov 2012 07:06:37 +0000 Subject: [PATCH] Documentation|Fixed: Various Doxygen apidoc fixes --- doomsday/engine/api/filetype.h | 2 +- doomsday/engine/api/uri.h | 6 ++--- doomsday/engine/include/filesys/searchpath.h | 1 + doomsday/engine/include/pathtree.h | 8 ++++--- doomsday/engine/include/resource/models.h | 2 +- doomsday/engine/include/uri.hh | 17 ++++++++++---- doomsday/engine/src/filesys/fs_namespace.cpp | 4 ++-- doomsday/engine/src/filesys/metafile.cpp | 7 +++--- doomsday/engine/src/filesys/searchpath.cpp | 2 +- doomsday/engine/src/pathtreenode.cpp | 5 ++-- doomsday/engine/src/uri.cpp | 24 ++++++++++---------- 11 files changed, 43 insertions(+), 35 deletions(-) diff --git a/doomsday/engine/api/filetype.h b/doomsday/engine/api/filetype.h index 6981f70026..49f854a846 100644 --- a/doomsday/engine/api/filetype.h +++ b/doomsday/engine/api/filetype.h @@ -154,7 +154,7 @@ namespace de * * @return The interpreted file; otherwise @c 0. */ - virtual de::File1* interpret(de::FileHandle& /*hndl*/, String /*path*/, FileInfo const& /*info*/) const = 0; + virtual de::File1* interpret(de::FileHandle& hndl, String path, FileInfo const& info) const = 0; }; /// @return @c true= @a ftype is a NativeFileType object. diff --git a/doomsday/engine/api/uri.h b/doomsday/engine/api/uri.h index 20c3b12855..123f65a9f3 100644 --- a/doomsday/engine/api/uri.h +++ b/doomsday/engine/api/uri.h @@ -85,7 +85,7 @@ Uri* Uri_New(void); * @param defaultResourceClasslasslass If no scheme is defined in @a path and this is not @c FC_NULL, * look for an appropriate default scheme for this class of resource. */ -Uri* Uri_NewWithPath2(char const* path, resourceclassid_t defResourceClasslasslasslass); +Uri* Uri_NewWithPath2(char const* path, resourceclassid_t defaultResourceClass); Uri* Uri_NewWithPath(char const* path); /** @@ -175,8 +175,8 @@ Uri* Uri_SetPath(Uri* uri, char const* path); * * @return Same as @a uri, for caller convenience. */ -Uri* Uri_SetUri2(Uri* uri, char const* path, resourceclassid_t defResourceClasslasslasslass); -Uri* Uri_SetUri(Uri* uri, char const* path/* defaultResourceClasslasslass = RC_UNKNOWN*/); +Uri* Uri_SetUri2(Uri* uri, char const* path, resourceclassid_t defaultResourceClass); +Uri* Uri_SetUri(Uri* uri, char const* path/* defaultResourceClass = RC_UNKNOWN*/); Uri* Uri_SetUriStr(Uri* uri, ddstring_t const* path); diff --git a/doomsday/engine/include/filesys/searchpath.h b/doomsday/engine/include/filesys/searchpath.h index 041d6cd87b..97872b5e04 100644 --- a/doomsday/engine/include/filesys/searchpath.h +++ b/doomsday/engine/include/filesys/searchpath.h @@ -49,6 +49,7 @@ namespace de { class SearchPath : public Uri { public: + /// @defgroup searchPathFlags Search Path Flags enum Flag { /// Interpreters should not decend into branches. diff --git a/doomsday/engine/include/pathtree.h b/doomsday/engine/include/pathtree.h index 9f8c72a696..15336ce478 100644 --- a/doomsday/engine/include/pathtree.h +++ b/doomsday/engine/include/pathtree.h @@ -145,7 +145,7 @@ namespace de Uri::hash_type hash() const; /** - * @param candidatePath Mapped search pattern (path). + * @param searchPattern Mapped search pattern (path). * @param flags @ref pathComparisonFlags * * @return Zero iff the candidate path matched this. @@ -154,8 +154,10 @@ namespace de * using another tree node (possibly from another PathTree), would * allow for further optimizations elsewhere (in the file system * for example) -ds + * + * @todo This logic should be encapsulated in Uri/Uri::PathNode -ds */ - int comparePath(de::Uri const& candidatePath, int flags) const; + int comparePath(de::Uri const& searchPattern, int flags) const; /** * Composes the URI for this node. 'Composing' the path of a node is to @@ -288,7 +290,7 @@ namespace de * @param parent Used in combination with @a flags= PCF_MATCH_PARENT * to limit the traversal to only the child nodes of * this node. - * @param hash If not @c PathTree::no_hash only consider nodes whose + * @param hashKey If not @c PathTree::no_hash only consider nodes whose * hashed name matches this. * @param callback Callback function ptr. * @param parameters Passed to the callback. diff --git a/doomsday/engine/include/resource/models.h b/doomsday/engine/include/resource/models.h index 967a7dc573..46a3a94fc1 100644 --- a/doomsday/engine/include/resource/models.h +++ b/doomsday/engine/include/resource/models.h @@ -37,7 +37,7 @@ typedef uint modelid_t; #define MAX_FRAME_MODELS DED_MAX_SUB_MODELS /** - * @def modelFrameFlags Model frame flags + * @defgroup modelFrameFlags Model frame flags */ ///@{ #define MFF_FULLBRIGHT 0x00000001 diff --git a/doomsday/engine/include/uri.hh b/doomsday/engine/include/uri.hh index 5ea13e9e53..8d4a2336b7 100644 --- a/doomsday/engine/include/uri.hh +++ b/doomsday/engine/include/uri.hh @@ -80,7 +80,6 @@ public: /** * Flags for printing URIs. - * @ingroup flags base */ enum PrintFlag { @@ -149,8 +148,10 @@ public: * @param defaultResourceClass If no scheme is defined in @a path and this * is not @c RC_NULL, ask the resource locator whether it knows of an * appropriate default scheme for this class of resource. + * + * @param sep Character used to separate path segments in @a path. */ - Uri(String path, resourceclassid_t defaultResourceClass = RC_UNKNOWN, QChar delimiter = '/'); + Uri(String path, resourceclassid_t defaultResourceClass = RC_UNKNOWN, QChar sep = '/'); /** * Construct a Uri instance by duplicating @a other. @@ -266,8 +267,10 @@ public: /** * Change the path of the URI to @a newPath. + * + * @param sep Character used to separate path segments in @a path. */ - Uri& setPath(String newPath, QChar delimiter = '/'); + Uri& setPath(String newPath, QChar sep = '/'); /** * Update this URI by parsing new values from the specified arguments. @@ -277,18 +280,22 @@ public: * @param defaultResourceClass If no scheme is defined in @a newUri and * this is not @c RC_NULL, ask the resource locator whether it knows * of an appropriate default scheme for this class of resource. + * + * @param sep Character used to separate path segments in @a path. */ Uri& setUri(String newUri, resourceclassid_t defaultResourceClass = RC_UNKNOWN, - QChar delimiter = '/'); + QChar sep = '/'); /** * Compose from this URI a plain-text representation. Any internal encoding * method or symbolic identifiers will be left unchanged in the resultant * string (not decoded, not resolved). * + * @param sep Character to use to replace path segment separators. + * * @return Plain-text String representation. */ - String compose(QChar delimiter = '/') const; + String compose(QChar sep = '/') const; /** * Retrieve the segment with index @a index. Note that segments are indexed diff --git a/doomsday/engine/src/filesys/fs_namespace.cpp b/doomsday/engine/src/filesys/fs_namespace.cpp index 62ed585197..a267fc96ad 100644 --- a/doomsday/engine/src/filesys/fs_namespace.cpp +++ b/doomsday/engine/src/filesys/fs_namespace.cpp @@ -1,7 +1,7 @@ /** - * @file filenamespace.cpp + * @file fs_namespace.cpp * - * File namespace. @ingroup fs + * File system namespace. @ingroup fs * * @author Copyright © 2003-2012 Jaakko Keränen * @author Copyright © 2006-2012 Daniel Swanson diff --git a/doomsday/engine/src/filesys/metafile.cpp b/doomsday/engine/src/filesys/metafile.cpp index f40346acec..ad810b8b6d 100644 --- a/doomsday/engine/src/filesys/metafile.cpp +++ b/doomsday/engine/src/filesys/metafile.cpp @@ -1,11 +1,10 @@ /** - * @file resourcerecord.cpp + * @file metafile.cpp * - * Resource Record. - * - * @ingroup resource + * MetaFile. @ingroup fs * * @author Copyright © 2010-2012 Daniel Swanson + * @author Copyright © 2010-2012 Jaakko Keränen * * @par License * GPL: http://www.gnu.org/licenses/gpl.html diff --git a/doomsday/engine/src/filesys/searchpath.cpp b/doomsday/engine/src/filesys/searchpath.cpp index 1f24583310..846ab58aad 100644 --- a/doomsday/engine/src/filesys/searchpath.cpp +++ b/doomsday/engine/src/filesys/searchpath.cpp @@ -25,7 +25,7 @@ namespace de { -SearchPath::SearchPath(Uri const& _uri, SearchPath::Flags _flags) +SearchPath::SearchPath(de::Uri const& _uri, SearchPath::Flags _flags) : Uri(_uri), flags_(_flags) {} diff --git a/doomsday/engine/src/pathtreenode.cpp b/doomsday/engine/src/pathtreenode.cpp index 5d5819b9c2..d227ae94eb 100644 --- a/doomsday/engine/src/pathtreenode.cpp +++ b/doomsday/engine/src/pathtreenode.cpp @@ -118,7 +118,7 @@ PathTree::Node& PathTree::Node::setUserValue(int value) return *this; } -/// @todo This logic should be encapsulated in Uri/Uri::PathNode +/// @todo This logic should be encapsulated in Uri/Uri::Segment static int matchName(char const* string, char const* pattern) { char const* in = string, *st = pattern; @@ -156,7 +156,6 @@ static int matchName(char const* string, char const* pattern) return *st == 0; } -/// @todo This logic should be encapsulated in Uri/Uri::PathNode int PathTree::Node::comparePath(de::Uri const& searchPattern, int flags) const { if(((flags & PCF_NO_LEAF) && isLeaf()) || @@ -165,7 +164,7 @@ int PathTree::Node::comparePath(de::Uri const& searchPattern, int flags) const try { - const de::Uri::Segment* snode = &searchPattern.firstSegment(); + de::Uri::Segment const* snode = &searchPattern.firstSegment(); // In reverse order, compare each path node in the search term. int pathNodeCount = searchPattern.segmentCount(); diff --git a/doomsday/engine/src/uri.cpp b/doomsday/engine/src/uri.cpp index b0ae183b83..344fcfcf65 100644 --- a/doomsday/engine/src/uri.cpp +++ b/doomsday/engine/src/uri.cpp @@ -87,7 +87,7 @@ struct Uri::Instance * Segment map of the path. The map is composed of two parts: the first * SEGMENT_BUFFER_SIZE elements are placed into a fixed-size buffer which is * allocated along with the Instance, and additional segments are allocated - * dynamically and linked in the @ref extraSegments list. + * dynamically and linked in the extraSegments list. * * This optimized representation should mean that the majority of paths * can be represented without dynamically allocating memory from the heap. @@ -375,12 +375,12 @@ struct Uri::Instance Instance(const Instance&); // no copying }; -Uri::Uri(String path, resourceclassid_t defaultResourceClass, QChar delimiter) +Uri::Uri(String path, resourceclassid_t defaultResourceClass, QChar sep) { d = new Instance(); if(!path.isEmpty()) { - setUri(path, defaultResourceClass, delimiter); + setUri(path, defaultResourceClass, sep); } } @@ -545,11 +545,11 @@ Uri& Uri::setScheme(String newScheme) return *this; } -Uri& Uri::setPath(String newPath, QChar delimiter) +Uri& Uri::setPath(String newPath, QChar sep) { - if(delimiter != '/') + if(sep != '/') { - newPath = newPath.replace(delimiter, QString("/"), Qt::CaseInsensitive); + newPath = newPath.replace(sep, QString("/"), Qt::CaseInsensitive); } d->path = newPath; d->clearCachedResolved(); @@ -557,13 +557,13 @@ Uri& Uri::setPath(String newPath, QChar delimiter) return *this; } -Uri& Uri::setUri(String rawUri, resourceclassid_t defaultResourceClass, QChar delimiter) +Uri& Uri::setUri(String rawUri, resourceclassid_t defaultResourceClass, QChar sep) { LOG_AS("Uri::setUri"); - if(delimiter != '/') + if(sep != '/') { - rawUri = rawUri.replace(delimiter, QString("/"), Qt::CaseInsensitive); + rawUri = rawUri.replace(sep, QString("/"), Qt::CaseInsensitive); } d->path = rawUri.trimmed(); @@ -573,7 +573,7 @@ Uri& Uri::setUri(String rawUri, resourceclassid_t defaultResourceClass, QChar de return *this; } -String Uri::compose(QChar delimiter) const +String Uri::compose(QChar sep) const { String result; if(!d->scheme.isEmpty()) @@ -584,9 +584,9 @@ String Uri::compose(QChar delimiter) const { result += d->path; } - if(delimiter != '/') + if(sep != '/') { - result = result.replace('/', delimiter, Qt::CaseInsensitive); + result = result.replace('/', sep, Qt::CaseInsensitive); } return result; }