libdeng2|FS: Attempting to improve readability of file descriptions

A file description now adapts to the current log entry metadata in
that more verbosity is included for developer/verbose entries.

PackageFolder now describes itself as a "package" rather than
"folder."

test_archive now tests the three possible levels of file description
(with a PackageFolder and a NativeFile).

doomsday/libdeng2/include/de/filesys/folder.h

@@ -101,6 +101,8 @@ class DENG2_PUBLIC Folder : public File
     virtual ~Folder();
 
     String describe() const;
+
+    String describeFeeds() const;
 
     /**
      * Populates the folder with a set of File instances. Each feed

doomsday/libdeng2/include/de/filesys/packagefolder.h

@@ -60,6 +60,8 @@ class PackageFolder : public Folder
 
     virtual ~PackageFolder();
 
+    String describe() const;
+
     /**
      * Returns the Archive of the package.
      */

doomsday/libdeng2/include/de/libdeng2.h

@@ -188,6 +188,8 @@
  */
 #define DENG2_UNUSED4(a, b, c, d) (void)a, (void)b, (void)c, (void)d
 
+#define DENG2_PLURAL_S(Count) ((Count) != 1? "s" : "")
+
 /**
  * Forms an escape sequence string literal. Escape sequences begin
  * with an ASCII Escape character.

doomsday/libdeng2/src/filesys/file.cpp

@@ -25,6 +25,7 @@
 #include "de/Date"
 #include "de/NumberValue"
 #include "de/Guard"
+#include "de/DirectoryFeed"
 
 namespace de {
 
@@ -122,23 +123,53 @@ String File::description() const
 {
     DENG2_GUARD(this);
 
+    // describe() gives the actual description of this file.
     String desc = describe();
-    if(parent())
-    {
-        desc += " at path \"" + path() + "\"";
-    }
+
     if(!mode().testFlag(Write))
     {
         desc = "read-only " + desc;
     }
-    if(source() != this)
+
+    // Check for additional contextual information that may be relevant. First
+    // determine if this is being called for a log entry.
+    Log &log = Log::threadLog();
+    int verbosity = 0;
+    if(!log.isStaging() || (log.currentEntryMetadata() & LogEntry::Dev))
+    {
+        // For dev entries and everything outside log entries, use a full description.
+        verbosity = 2;
+    }
+    else if((log.currentEntryMetadata() & LogEntry::LevelMask) <= LogEntry::Verbose)
+    {
+        // Verbose entries can contain some additional information.
+        verbosity = 1;
+    }
+
+    if(verbosity >= 1)
     {
-        desc += " (sourced from " + source()->description() + ")";
+        if(parent())
+        {
+            desc += " [path \"" + path() + "\"]";
+        }
     }
-    if(originFeed())
+
+    // In case of DirectoryFeed, the native file desciption itself already contains
+    // information about the full native path, so we don't have to describe the
+    // feed itself (would be redundant).
+    if(originFeed() && (verbosity >= 2 || !originFeed()->is<DirectoryFeed>()))
     {
-        desc += " (out of " + originFeed()->description() + ")";
+        desc += " from " + originFeed()->description();
     }
+
+    if(verbosity >= 2)
+    {
+        if(source() != this)
+        {
+            desc += " (data sourced from " + source()->description() + ")";
+        }
+    }
+
     return desc;
 }
 

doomsday/libdeng2/src/filesys/folder.cpp

@@ -59,18 +59,49 @@ String Folder::describe() const
 {
     DENG2_GUARD(this);
 
-    String desc = String("folder \"%1\" (with %2 items from %3 feeds")
-            .arg(name()).arg(_contents.size()).arg(_feeds.size());
+    String desc = String("folder \"%1\"").arg(name());
 
-    if(!_feeds.empty())
+    String const feedDesc = describeFeeds();
+    if(!feedDesc.isEmpty())
     {
+        desc += String(" (%1)").arg(feedDesc);
+    }
+
+    return desc;
+}
+
+String Folder::describeFeeds() const
+{
+    DENG2_GUARD(this);
+
+    String desc;
+
+    if(_feeds.size() == 1)
+    {
+        desc += String("contains %1 file%2 from %3")
+                .arg(_contents.size())
+                .arg(DENG2_PLURAL_S(_contents.size()))
+                .arg(_feeds.front()->description());
+    }
+    else if(_feeds.size() > 1)
+    {
+        desc += String("contains %1 file%2 from %3 feed%4")
+                .arg(_contents.size())
+                .arg(DENG2_PLURAL_S(_contents.size()))
+                .arg(_feeds.size())
+                .arg(DENG2_PLURAL_S(_feeds.size()));
+
         int n = 0;
         DENG2_FOR_EACH_CONST(Feeds, i, _feeds)
         {
-            desc += String("; feed #%1 is %2").arg(++n).arg((*i)->description());
+            desc += String("; feed #%2 is %3")
+                    .arg(n + 1)
+                    .arg((*i)->description());
+            ++n;
         }
     }
-    return desc + ")";
+
+    return desc;
 }
 
 void Folder::clear()

doomsday/libdeng2/src/filesys/packagefolder.cpp

@@ -34,6 +34,21 @@ PackageFolder::~PackageFolder()
     deindex();
 }
 
+String PackageFolder::describe() const
+{
+    DENG2_GUARD(this);
+
+    String desc = String("package \"%1\"").arg(name());
+
+    String const feedDesc = describeFeeds();
+    if(!feedDesc.isEmpty())
+    {
+        desc += String(" (%1)").arg(feedDesc);
+    }
+
+    return desc;
+}
+
 Archive &PackageFolder::archive()
 {
     DENG2_ASSERT(!feeds().empty());

doomsday/tests/test_archive/main.cpp

@@ -48,6 +48,10 @@ int main(int argc, char **argv)
         LOG_MSG("Here's test.zip's info:\n") << zip.info();
         LOG_MSG("Root folder's info:\n") << app.rootFolder().info();
 
+        LOG_MSG    ("General description: %s")   << zip.description();
+        LOG_VERBOSE("Verbose description: %s")   << zip.description();
+        LOGDEV_MSG ("Developer description: %s") << zip.description();
+
         File const &hello = zip.locate<File>("hello.txt");
         File::Status stats = hello.status();
         LOG_MSG("hello.txt size: %i bytes, modified at %s") << stats.size << Date(stats.modifiedAt);
@@ -76,6 +80,10 @@ int main(int argc, char **argv)
         Writer(zip2) << arch;
         LOG_MSG("Wrote ") << zip2.path();
         LOG_MSG("") << zip2.info();
+
+        LOG_MSG    ("General description: %s")   << zip2.description();
+        LOG_VERBOSE("Verbose description: %s")   << zip2.description();
+        LOGDEV_MSG ("Developer description: %s") << zip2.description();
     }
     catch(Error const &err)
     {