docs: add missing modules documentation and fix some code smells

Signed-off-by: Luís Ferreira <contact@lsferreira.net> Signed-off-by: Luís Ferreira <contact@lsferreira.net>
labcif · Jul 18, 2021 · 9c37d7e · 9c37d7e
1 parent 33eb17b
commit 9c37d7e
Show file tree

Hide file tree

Showing 18 changed files with 228 additions and 22 deletions.
diff --git a/source/gboardforensics/analysis/dir.d b/source/gboardforensics/analysis/dir.d
@@ -1,3 +1,11 @@
+/**
+ * Module representing the directory detector and analysis logic for directories
+ *
+ * Authors: João Lourenço, Luís Ferreira
+ * Copyright: João Lourenço (c) 2021
+ *            Luís Ferreira (c) 2021
+ * License: GPL-3.0
+ */
 module gboardforensics.analysis.dir;
 
 import gboardforensics.gatherers;
@@ -6,21 +14,40 @@ import gboardforensics.analysis;
 import std.file;
 import std.path;
 
+/**
+ * This represents the directory auto detector logic to match a given gatherer
+ */
 struct DirDetector
 {
+	/**
+	 * Constructs a directory detector with a given folder path
+	 *
+	 * Params:
+	 *   path = path to the folder to be detected
+	 */
 	this(string path)
 		in (path.exists())
 		in (path.isDir())
 	{
 		this.dir = DirEntry(path);
 	}
 
+	/**
+	 * Constructs a directory detector with a given directory entry
+	 * Params:
+	 *   dir = directory entry representing a folder to be detected
+	 */
 	this(DirEntry dir)
 		in (dir.isDir())
 	{
 		this.dir = dir;
 	}
 
+	/**
+	 * Detects the gatherer associated to the given folder
+	 *
+	 * Returns: the detected gatherer or null if not found
+	 */
 	IGatherer detect()
 	{
 		switch (dir.name.baseName())
@@ -30,7 +57,7 @@ struct DirDetector
 		}
 	}
 
-	DirEntry dir;
+	private DirEntry dir;
 }
 
 /**

diff --git a/source/gboardforensics/analysis/file.d b/source/gboardforensics/analysis/file.d
@@ -1,3 +1,11 @@
+/**
+ * Module representing the file detector and analysis logic for files
+ *
+ * Authors: João Lourenço, Luís Ferreira
+ * Copyright: João Lourenço (c) 2021
+ *            Luís Ferreira (c) 2021
+ * License: GPL-3.0
+ */
 module gboardforensics.analysis.file;
 
 import gboardforensics.gatherers;
@@ -56,7 +64,7 @@ struct FileDetector
 	 */
 	public IGatherer detect()
 	{
-		byte[] buf = file.rawRead(new byte[SQLITE3_SIGNATURE.length]);
+		const byte[] buf = file.rawRead(new byte[SQLITE3_SIGNATURE.length]);
 
 		// detect SQLite3 file
 		if(buf.length == SQLITE3_SIGNATURE.length && buf == SQLITE3_SIGNATURE)

diff --git a/source/gboardforensics/analysis/package.d b/source/gboardforensics/analysis/package.d
@@ -1,3 +1,11 @@
+/**
+ * Package representing the analysis logic
+ *
+ * Authors: João Lourenço, Luís Ferreira
+ * Copyright: João Lourenço (c) 2021
+ *            Luís Ferreira (c) 2021
+ * License: GPL-3.0
+ */
 module gboardforensics.analysis;
 
 import gboardforensics.gatherers;
@@ -90,16 +98,19 @@ struct AnalysisData
 		this.clipboard ~= gatherer.clipboard;
 	}
 
+	/// ditto
 	void add(ExpressionHistoryGatherer gather)
 	{
 		this.expressionHistory ~= gather.expressionHistory;
 	}
 
+	/// ditto
 	void add(TranslateCacheGatherer gatherer)
 	{
 		this.translateCache ~= gatherer.translateCache;
 	}
 
+	/// ditto
 	auto opOpAssign(string op, T : AnalysisData)(T value)
 		if (op == "~")
 	{

diff --git a/source/gboardforensics/gatherers/clipboard.d b/source/gboardforensics/gatherers/clipboard.d
@@ -1,3 +1,11 @@
+/**
+ * This module represents the gatherer logic for the clipboard manager
+ *
+ * Authors: João Lourenço, Luís Ferreira
+ * Copyright: João Lourenço (c) 2021
+ *            Luís Ferreira (c) 2021
+ * License: GPL-3.0
+ */
 module gboardforensics.gatherers.clipboard;
 
 import gboardforensics.gatherers;
@@ -73,7 +81,7 @@ class ClipboardGatherer : IGatherer
 	/**
 	 * Gets the collected clipboard
 	 *
-	 * Returns: clipboard data structure
+	 * Returns: clipboard data serializable structure
 	 */
 	@property const(Clipboard) clipboard() const
 	{

diff --git a/source/gboardforensics/gatherers/dictionary.d b/source/gboardforensics/gatherers/dictionary.d
@@ -1,3 +1,11 @@
+/**
+ * This module represents the gatherer logic for the personal dictionary
+ *
+ * Authors: João Lourenço, Luís Ferreira
+ * Copyright: João Lourenço (c) 2021
+ *            Luís Ferreira (c) 2021
+ * License: GPL-3.0
+ */
 module gboardforensics.gatherers.dictionary;
 
 import gboardforensics.gatherers;

diff --git a/source/gboardforensics/gatherers/expressionhistory.d b/source/gboardforensics/gatherers/expressionhistory.d
@@ -1,3 +1,11 @@
+/**
+ * This module represents the gatherer logic for the expression history
+ *
+ * Authors: João Lourenço, Luís Ferreira
+ * Copyright: João Lourenço (c) 2021
+ *            Luís Ferreira (c) 2021
+ * License: GPL-3.0
+ */
 module gboardforensics.gatherers.expressionhistory;
 
 import gboardforensics.gatherers;

diff --git a/source/gboardforensics/gatherers/package.d b/source/gboardforensics/gatherers/package.d
@@ -1,3 +1,11 @@
+/**
+ * Package representing all the gatherers of GBoard sources
+ *
+ * Authors: João Lourenço, Luís Ferreira
+ * Copyright: João Lourenço (c) 2021
+ *            Luís Ferreira (c) 2021
+ * License: GPL-3.0
+ */
 module gboardforensics.gatherers;
 
 public {

diff --git a/source/gboardforensics/gatherers/translatecache.d b/source/gboardforensics/gatherers/translatecache.d
@@ -1,3 +1,11 @@
+/**
+ * This module represents the gatherer logic for the translate cache
+ *
+ * Authors: João Lourenço, Luís Ferreira
+ * Copyright: João Lourenço (c) 2021
+ *            Luís Ferreira (c) 2021
+ * License: GPL-3.0
+ */
 module gboardforensics.gatherers.translatecache;
 
 import gboardforensics.gatherers : IGatherer;
@@ -10,14 +18,24 @@ import std.range : assocArray, back, front, split, tail;
 import std.regex : matchFirst, regex;
 import std.typecons : No, tuple;
 
+/**
+ * This represents a gatherer for GBoard Translate cache
+ */
 class TranslateCacheGatherer : IGatherer
 {
+	/**
+	 * Constructs a gatherer with a given folder path
+	 *
+	 * Params:
+	 *   _dir = path to the translate cache folder
+	 */
 	this(DirEntry _dir)
 		in (_dir.isDir())
 	{
 		this._dir = _dir;
 	}
 
+	///
 	void gather()
 	{
 		import std.array : array;
@@ -41,7 +59,11 @@ class TranslateCacheGatherer : IGatherer
 			.array;
 	}
 
-
+	/**
+	 * Gets the collected translate cache
+	 *
+	 * Returns: translate cache serializable structure
+	 */
 	@property const(TranslateCache) translateCache() const
 	{
 		return _cache;

diff --git a/source/gboardforensics/models/clipboard.d b/source/gboardforensics/models/clipboard.d
@@ -1,3 +1,11 @@
+/**
+ * Module representing the serializable model of a Clipboard data source
+ *
+ * Authors: João Lourenço, Luís Ferreira
+ * Copyright: João Lourenço (c) 2021
+ *            Luís Ferreira (c) 2021
+ * License: GPL-3.0
+ */
 module gboardforensics.models.clipboard;
 
 import gboardforensics.utils.serialization;

diff --git a/source/gboardforensics/models/dictionary.d b/source/gboardforensics/models/dictionary.d
@@ -1,3 +1,11 @@
+/**
+ * Module representing the serializable model of dictionary data source
+ *
+ * Authors: João Lourenço, Luís Ferreira
+ * Copyright: João Lourenço (c) 2021
+ *            Luís Ferreira (c) 2021
+ * License: GPL-3.0
+ */
 module gboardforensics.models.dictionary;
 
 import gboardforensics.utils.serialization;
@@ -32,6 +40,13 @@ struct Dictionary
 		return entries.length;
 	}
 
+	/**
+	 * Construct a dictionary
+	 *
+	 * Params:
+	 *   path = path of the dictionary
+	 *   entries = list of dictionary entries
+	 */
 	@safe pure nothrow @nogc
 	this(string path, const(Entry)[] entries)
 	{

diff --git a/source/gboardforensics/models/expressionhistory.d b/source/gboardforensics/models/expressionhistory.d
@@ -1,3 +1,12 @@
+/**
+ * Module representing a serializable model of an Expression History data
+ * source.
+ *
+ * Authors: João Lourenço, Luís Ferreira
+ * Copyright: João Lourenço (c) 2021
+ *            Luís Ferreira (c) 2021
+ * License: GPL-3.0
+ */
 module gboardforensics.models.expressionhistory;
 
 import asdf.serialization;
@@ -30,6 +39,9 @@ struct ExpressionHistory
 		@serdeIgnoreDefault int shares;
 	}
 
+	/**
+	 * This represents a single entry in the emoticons table
+	 */
 	struct Emoticon
 	{
 		/// Emoticon text representation

diff --git a/source/gboardforensics/models/package.d b/source/gboardforensics/models/package.d
@@ -1,3 +1,11 @@
+/**
+ * Package representing all the serializable models
+ *
+ * Authors: João Lourenço, Luís Ferreira
+ * Copyright: João Lourenço (c) 2021
+ *            Luís Ferreira (c) 2021
+ * License: GPL-3.0
+ */
 module gboardforensics.models;
 
 public

diff --git a/source/gboardforensics/models/trainingcache.d b/source/gboardforensics/models/trainingcache.d
@@ -1,3 +1,11 @@
+/**
+ * Module representing the serializable model of training cache data source
+ *
+ * Authors: João Lourenço, Luís Ferreira
+ * Copyright: João Lourenço (c) 2021
+ *            Luís Ferreira (c) 2021
+ * License: GPL-3.0
+ */
 module gboardforensics.models.trainingcache;
 
 import gboardforensics.utils.serialization;
@@ -6,16 +14,27 @@ import std.typecons : Nullable;
 
 import asdf.serialization : serdeIgnore, serdeIgnoreDefault;
 
+/**
+ * Serializable model of the training cache data source
+ */
 struct TrainingCache
 {
+	/**
+	 * Serializable representation of a training cache entry
+	 */
 	struct Info
 	{
-		string time;
-		string sequence;
-		@serdeIgnoreDefault Nullable!bool deleted;
-		size_t timestamp;
+		string time; /// text representation of the timestamp field
+		string sequence; /// character sequence of the entry
+		@serdeIgnoreDefault Nullable!bool deleted; /// wether the field is deleted or inserted, if applicable
+		size_t timestamp; /// timestamp in UNIX epoch (milliseconds)
 	}
 
+	/**
+	 * Count number of entries fetched
+	 *
+	 * Returns: number of entries
+	 */
 	@safe pure nothrow
 	size_t countItems() const
 	{