From 77540dacbbc4f74545c3f67a72c136a37329b132 Mon Sep 17 00:00:00 2001
From: Alex Cabal <alex@alexcabal.com>
Date: Thu, 5 Dec 2024 11:22:37 -0600
Subject: [PATCH] Clarify comments

---
 lib/Ebook.php                 | 12 ++++++++----
 scripts/update-ebook-database |  2 +-
 2 files changed, 9 insertions(+), 5 deletions(-)

diff --git a/lib/Ebook.php b/lib/Ebook.php
index 386cf729..1b007aef 100644
--- a/lib/Ebook.php
+++ b/lib/Ebook.php
@@ -19,7 +19,7 @@ use function Safe\shell_exec;
  * @property array<Contributor> $Illustrators
  * @property array<Contributor> $Translators
  * @property array<Contributor> $Contributors
- * @property ?array<string> $TocEntries
+ * @property ?array<string> $TocEntries A list of non-Roman ToC entries *only if* the work has the `se:is-a-collection` metadata element; `null` otherwise.
  * @property string $Url
  * @property bool $HasDownloads
  * @property string $UrlSafeIdentifier
@@ -34,7 +34,7 @@ use function Safe\shell_exec;
  * @property string $ReadingEaseDescription
  * @property string $ReadingTime
  * @property string $AuthorsHtml
- * @property string $AuthorsUrl
+ * @property string $AuthorsUrl This is a single URL even if there are multiple authors; for example, `/ebooks/karl-marx_friedrich-engels/`.
  * @property string $ContributorsHtml
  * @property string $TitleWithCreditsHtml
  * @property string $TextUrl
@@ -65,9 +65,13 @@ class Ebook{
 	public float $ReadingEase;
 	public ?string $GitHubUrl = null;
 	public ?string $WikipediaUrl = null;
+	/** When the ebook was published. */
 	public DateTimeImmutable $EbookCreated;
+	/** When the ebook was updated. */
 	public DateTimeImmutable $EbookUpdated;
+	/** When the database row was created. */
 	public DateTimeImmutable $Created;
+	/** When the database row was updated. */
 	public DateTimeImmutable $Updated;
 	public ?int $TextSinglePageByteCount = null;
 
@@ -90,7 +94,7 @@ class Ebook{
 	/** @var array<Contributor> $_Contributors */
 	protected array $_Contributors;
 	/** @var ?array<string> $_TocEntries */
-	protected ?array $_TocEntries = null; // A list of non-Roman ToC entries *only if* the work has the `se:is-a-collection` metadata element; `null` otherwise.
+	protected ?array $_TocEntries = null;
 	protected string $_Url;
 	protected bool $_HasDownloads;
 	protected string $_UrlSafeIdentifier;
@@ -105,7 +109,7 @@ class Ebook{
 	protected string $_ReadingEaseDescription;
 	protected string $_ReadingTime;
 	protected string $_AuthorsHtml;
-	protected string $_AuthorsUrl; // This is a single URL even if there are multiple authors; for example, `/ebooks/karl-marx_friedrich-engels/`.
+	protected string $_AuthorsUrl;
 	protected string $_ContributorsHtml;
 	protected string $_TitleWithCreditsHtml;
 	protected string $_TextUrl;
diff --git a/scripts/update-ebook-database b/scripts/update-ebook-database
index 7cb69f3c..726067ff 100755
--- a/scripts/update-ebook-database
+++ b/scripts/update-ebook-database
@@ -15,7 +15,7 @@ if(isset($options['v']) || isset($options['verbose'])){
 }
 
 if($ebookWwwFilesystemPath === null){
-	print("Expected usage: update-ebook-database [-v,--verbose] --ebook-www-filesystem-path <path>\n");
+	print("Usage: update-ebook-database [-v,--verbose] --ebook-www-filesystem-path PATH\n");
 	exit(1);
 }