add JSdocs

Author: ScriptRaccoon

scripts/deduce-category-implications.ts

@@ -4,16 +4,27 @@ import dotenv from 'dotenv'
 
 dotenv.config({ quiet: true })
 
+/**
+ * Deduces implications from given ones.
+ */
 export async function deduce_category_implications(db: Client) {
 	await clear_deduced_category_implications(db)
 	await create_dualized_category_implications(db)
 	await create_self_dual_category_implications(db)
 }
 
+/**
+ * Clears all deduced implications. This is done as a first step.
+ */
 async function clear_deduced_category_implications(db: Client) {
 	await db.execute(`DELETE FROM implications WHERE is_deduced = TRUE`)
 }
 
+/**
+ * Dualizes all implications by dualizing the involved properties
+ * (in case they have a dual). For example, if P ===> Q holds,
+ * then P^op ===> Q^op holds as well.
+ */
 async function create_dualized_category_implications(db: Client) {
 	const res = await db.execute(`
         SELECT
@@ -91,6 +102,10 @@ async function create_dualized_category_implications(db: Client) {
 	console.info(`Dualized ${dualizable_implications.length} category implications`)
 }
 
+/**
+ * Creates all trivial implications of the form
+ * self-dual + P ===> P^op
+ */
 async function create_self_dual_category_implications(db: Client) {
 	const { rows } = await db.execute(`
         INSERT INTO implication_input (

scripts/deduce-category-properties.ts

@@ -15,6 +15,10 @@ type CategoryMeta = {
 	dual_category_id: string | null
 }
 
+/**
+ * Deduce properties of categories from given ones
+ * by using the list of implications.
+ */
 export async function deduce_category_properties(db: Client) {
 	const tx = await db.transaction()
 
@@ -53,6 +57,20 @@ export async function deduce_category_properties(db: Client) {
 	}
 }
 
+/**
+ * Implications have the form:
+ *
+ * P_1 + ... + P_n ----> Q_1 + ... + Q_m
+ *
+ * or
+ *
+ * P_1 + ... + P_n <---> Q_1 + ... + Q_m
+ *
+ * This function decomposes them into normalized implications,
+ * which have the form:
+ *
+ * P_1 + ... + P_n ----> Q
+ */
 async function get_normalized_category_implications(
 	tx: Transaction,
 ): Promise<NormalizedCategoryImplication[]> {
@@ -113,6 +131,9 @@ async function get_normalized_category_implications(
 	return implications
 }
 
+/**
+ * Returns the list of categories saved in the database.
+ */
 async function get_categories(tx: Transaction) {
 	const res = await tx.execute(`
 		SELECT id, name, dual_category_id
@@ -121,6 +142,10 @@ async function get_categories(tx: Transaction) {
 	return res.rows as unknown as CategoryMeta[]
 }
 
+/**
+ * Clears all the deduced properties.
+ * This runs before the deduction starts.
+ */
 async function delete_deduced_category_properties(tx: Transaction, category_id: string) {
 	await tx.execute({
 		sql: `
@@ -131,6 +156,10 @@ async function delete_deduced_category_properties(tx: Transaction, category_id:
 	})
 }
 
+/**
+ * Returns the list of properties that are satisfied or unsatisfied
+ * for a given category.
+ */
 async function get_decided_properties(
 	tx: Transaction,
 	category_id: string,
@@ -148,6 +177,10 @@ async function get_decided_properties(
 	return new Set(res.rows.map((row) => row.property_id) as string[])
 }
 
+/**
+ * Deduce satisfied properties for a given category from given ones
+ * by using the list of normalized implications.
+ */
 async function deduce_satisfied_category_properties(
 	tx: Transaction,
 	category_id: string,
@@ -208,6 +241,10 @@ async function deduce_satisfied_category_properties(
 	)
 }
 
+/**
+ * Deduce unsatisfied properties for a given category from given ones
+ * by using the satisfied properties and the list of normalized implications.
+ */
 async function deduce_unsatisfied_category_properties(
 	tx: Transaction,
 	category_id: string,
@@ -287,6 +324,10 @@ async function deduce_unsatisfied_category_properties(
 	)
 }
 
+/**
+ * Assign dual properties to dual categories:
+ * If C has property P, then C^op has property P^op (if defined).
+ */
 async function deduce_dual_category_properties(tx: Transaction, category: CategoryMeta) {
 	const res = await tx.execute({
 		sql: `

scripts/deduce-functor-implications.ts

@@ -6,15 +6,27 @@ dotenv.config({ quiet: true })
 
 // TODO: remove code duplication with category implication deduction script
 
+/**
+ * Deduces functor implications from given ones.
+ */
 export async function deduce_functor_implications(db: Client) {
 	await clear_deduced_functor_implications(db)
 	await create_dualized_functor_implications(db)
 }
 
+/**
+ * Clears all deduced functor implications. This is done as a first step.
+ */
 async function clear_deduced_functor_implications(db: Client) {
 	await db.execute(`DELETE FROM functor_implications WHERE is_deduced = TRUE`)
 }
 
+/**
+ * Dualizes all functor implications by dualizing the involved properties
+ * (in case they have a dual). For example, if P ===> Q holds,
+ * then P^op ===> Q^op holds as well. The assumptions of source and target
+ * categories (if any) need to be dualized as well.
+ */
 async function create_dualized_functor_implications(db: Client) {
 	const res = await db.execute(`
         SELECT

scripts/deduce-functor-properties.ts

@@ -21,6 +21,10 @@ type FunctorMeta = {
 // TODO: remove code duplication with category deduction script
 // (not quite the same because we need source and target assumptions)
 
+/**
+ * Deduce properties of functor from given ones
+ * by using the list of functor implications.
+ */
 export async function deduce_functor_properties(db: Client) {
 	const tx = await db.transaction()
 
@@ -43,6 +47,20 @@ export async function deduce_functor_properties(db: Client) {
 	}
 }
 
+/**
+ * Implications have the form:
+ *
+ * P_1 + ... + P_n ----> Q_1 + ... + Q_m
+ *
+ * or
+ *
+ * P_1 + ... + P_n <---> Q_1 + ... + Q_m
+ *
+ * This function decomposes them into normalized implications,
+ * which have the form:
+ *
+ * P_1 + ... + P_n ----> Q
+ */
 async function get_normalized_functor_implications(
 	tx: Transaction,
 ): Promise<NormalizedFunctorImplication[]> {
@@ -113,6 +131,10 @@ async function get_normalized_functor_implications(
 	return implications
 }
 
+/**
+ * Returns the list of functors saved in the database along with
+ * the satisfied properties of their source and target category.
+ */
 async function get_functors(tx: Transaction) {
 	const res = await tx.execute(`
 		SELECT
@@ -148,6 +170,10 @@ async function get_functors(tx: Transaction) {
 	})) as FunctorMeta[]
 }
 
+/**
+ * Clears all the deduced functor properties.
+ * This runs before the deduction starts.
+ */
 async function delete_deduced_functor_properties(tx: Transaction, functor: FunctorMeta) {
 	await tx.execute({
 		sql: `
@@ -158,6 +184,10 @@ async function delete_deduced_functor_properties(tx: Transaction, functor: Funct
 	})
 }
 
+/**
+ * Returns the list of properties that are satisfied or unsatisfied
+ * for a given functor.
+ */
 async function get_decided_functor_properties(
 	tx: Transaction,
 	functor_id: string,
@@ -175,6 +205,10 @@ async function get_decided_functor_properties(
 	return new Set(res.rows.map((row) => row.property_id) as string[])
 }
 
+/**
+ * Deduce satisfied properties for a given functor from given ones
+ * by using the list of normalized implications.
+ */
 async function deduce_satisfied_functor_properties(
 	tx: Transaction,
 	functor: FunctorMeta,
@@ -235,6 +269,10 @@ async function deduce_satisfied_functor_properties(
 	)
 }
 
+/**
+ * Deduce unsatisfied properties for a given functor from given ones
+ * by using the satisfied properties and the list of normalized implications.
+ */
 async function deduce_unsatisfied_functor_properties(
 	tx: Transaction,
 	functor: FunctorMeta,

scripts/deduce-special-morphisms.ts

@@ -7,6 +7,10 @@ export async function deduce_special_morphisms(db: Client) {
 	// e.g. regular monomorphisms = same as monomorphisms in mono-regular categories,
 }
 
+/**
+ * Deduce special morphisms in dual categories.
+ * For example, monomorphisms in C describe epimorphisms in C^op.
+ */
 async function deduce_special_morphisms_of_dual_categories(db: Client) {
 	const res = await db.execute(`
         INSERT INTO special_morphisms (category_id, type, description, reason)

scripts/deduce-special-objects.ts

@@ -4,6 +4,10 @@ export async function deduce_special_objects(db: Client) {
 	await deduce_special_objects_of_dual_categories(db)
 }
 
+/**
+ * Deduce special objects in dual categories.
+ * For example, initial objects in C describe the terminal objects in C^op.
+ */
 async function deduce_special_objects_of_dual_categories(db: Client) {
 	const res = await db.execute(`
         INSERT INTO special_objects (category_id, type, description)