From 9c37d7efb19435a6296e5d40335866bb95cbc385 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lu=C3=ADs=20Ferreira?= Date: Fri, 16 Jul 2021 16:33:15 +0100 Subject: [PATCH] docs: add missing modules documentation and fix some code smells MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Luís Ferreira Signed-off-by: Luís Ferreira --- source/gboardforensics/analysis/dir.d | 29 ++++++++++++- source/gboardforensics/analysis/file.d | 10 ++++- source/gboardforensics/analysis/package.d | 11 +++++ source/gboardforensics/gatherers/clipboard.d | 10 ++++- source/gboardforensics/gatherers/dictionary.d | 8 ++++ .../gatherers/expressionhistory.d | 8 ++++ source/gboardforensics/gatherers/package.d | 8 ++++ .../gatherers/translatecache.d | 24 ++++++++++- source/gboardforensics/models/clipboard.d | 8 ++++ source/gboardforensics/models/dictionary.d | 15 +++++++ .../models/expressionhistory.d | 12 ++++++ source/gboardforensics/models/package.d | 8 ++++ source/gboardforensics/models/trainingcache.d | 27 ++++++++++-- .../gboardforensics/models/translatecache.d | 43 ++++++++++++++----- source/gboardforensics/reporters/html.d | 11 ++++- source/gboardforensics/reporters/json.d | 8 ++++ source/gboardforensics/reporters/package.d | 8 ++++ source/gboardforensics/utils/serialization.d | 2 +- 18 files changed, 228 insertions(+), 22 deletions(-) diff --git a/source/gboardforensics/analysis/dir.d b/source/gboardforensics/analysis/dir.d index 4900cf5..a34f874 100644 --- 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,8 +14,17 @@ 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()) @@ -15,12 +32,22 @@ struct DirDetector 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 index 962ab84..2c61e93 100644 --- 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 index b6d799a..490caaa 100644 --- 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 index 023f420..c87c8a3 100644 --- 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 index 05e2e2c..eb47cc3 100644 --- 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 index acdb10c..8614c33 100644 --- 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 index 85c92cf..47b75e8 100644 --- 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 index a7f3541..59096cd 100644 --- 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 index 4dee157..ed6c427 100644 --- 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 index 14fe1b6..1481a2c 100644 --- 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 index c256091..9cae8db 100644 --- 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 index 7ed9c7b..f438fe5 100644 --- 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 index 3dab866..99e2a9f 100644 --- 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 { diff --git a/source/gboardforensics/models/translatecache.d b/source/gboardforensics/models/translatecache.d index 1f63144..b9c30dc 100644 --- a/source/gboardforensics/models/translatecache.d +++ b/source/gboardforensics/models/translatecache.d @@ -1,3 +1,12 @@ +/** + * Module representing the serializable model of the Translation 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.translatecache; import gboardforensics.utils.serialization; @@ -6,27 +15,39 @@ import std.typecons : Nullable; import asdf.serialization : serdeIgnore, serdeIgnoreDefault; +/** + * Serializable model of the Translation Cache data source + */ struct TranslateCache { + /** + * Entry representing each pair of request and response + */ struct Data { - size_t timestamp; - string time; - string orig; - string trans; - string from; - string to; - string requestURL; - string rawRequest; - string rawResponse; - string requestPath; - string responsePath; + size_t timestamp; /// Timestamp in UNIX epoch (milliseconds) + string time; /// Text representation of the timestamp field + string orig; /// Original text to be translated + string trans; /// Translated text + string from; /// Source language + string to; /// Target language + string requestURL; /// Request URL to Google internal API + string rawRequest; /// Raw request data encoded in base64 + string rawResponse; /// Raw response data encoded in base64 + string requestPath; /// Path where the request is stored + string responsePath; /// Path where the response is stored } + /** + * Count number of entries fetched + * + * Returns: number of entries + */ @safe pure nothrow size_t countItems() const { return data.length; } + /// Serializable array of entries SerializableArray!(const(Data)) data; } diff --git a/source/gboardforensics/reporters/html.d b/source/gboardforensics/reporters/html.d index f3e16ff..a980e9a 100644 --- a/source/gboardforensics/reporters/html.d +++ b/source/gboardforensics/reporters/html.d @@ -1,3 +1,11 @@ +/** + * This module represents the HTML output reporter + * + * 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.reporters.html; import std.datetime; @@ -25,8 +33,7 @@ class HTMLReporter : Reporter import std.array : appender; import diet.html : compileHTMLDietFile; - // explicit mutable copy of data - AnalysisData data = this.data; + const AnalysisData data = this.data; auto dst = appender!string(); dst.compileHTMLDietFile!("report.dt", diff --git a/source/gboardforensics/reporters/json.d b/source/gboardforensics/reporters/json.d index 502d5e7..1b4d96a 100644 --- a/source/gboardforensics/reporters/json.d +++ b/source/gboardforensics/reporters/json.d @@ -1,3 +1,11 @@ +/** + * This module represents the JSON output reporter + * + * 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.reporters.json; import asdf.serialization; diff --git a/source/gboardforensics/reporters/package.d b/source/gboardforensics/reporters/package.d index 8f39f16..89d9866 100644 --- a/source/gboardforensics/reporters/package.d +++ b/source/gboardforensics/reporters/package.d @@ -1,3 +1,11 @@ +/** + * Package representing the output reporters + * + * 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.reporters; import gboardforensics.analysis; diff --git a/source/gboardforensics/utils/serialization.d b/source/gboardforensics/utils/serialization.d index 935a334..024383c 100644 --- a/source/gboardforensics/utils/serialization.d +++ b/source/gboardforensics/utils/serialization.d @@ -43,7 +43,7 @@ struct SerializableArray(T) pure unittest { - SerializableArray!int b; + immutable SerializableArray!int b; assert(b == []); assert("[]" == b.serializeToJson!());