add documentation to dots_registers_delete.xqm

Author: philippepons

repo/backend/dots_registers_delete.xqm

@@ -1,10 +1,14 @@
-xquery version "3.1";
+xquery version "4.0";
 
-(:~  
-: Ce module permet à un utilisateur de DoTS de supprimer les registres DoTS du projet de son choix
-: @author École nationale des chartes
-: @since 2023-10-12
-: @version  1.0
+(:~
+: Module to delete DoTS project registers from a specified database.
+: This module allows a DoTS user to:
+: - remove the project entry from the central "dots" database (dots_db_switcher.xml),
+: - optionally delete the entire project database, or just its DoTS registers 
+:   ("resources.xml" and "fragments.xml").
+: Author: École nationale des chartes  
+: Since: 2023-10-12  
+: Version: 1.0
 :)
 module namespace dots.delete = "backend/dots_registers_delete";
 
@@ -13,11 +17,26 @@ import module namespace G = "globals";
 declare default element namespace "https://github.com/chartes/dots/";
 declare namespace dct = "http://purl.org/dc/terms/";
 
+(:~
+: Deletes DoTS registers for a given project.
+: @param  $dbName Name of the project database.
+: @param  $option If "true", the entire database is dropped.
+:                 If not, only the registers ("resources.xml" and "fragments.xml") are deleted.
+: @return Performs update operations in the "dots" database and optionally removes the project database.
+:)
 declare updating function dots.delete:handle($dbName as xs:string, $option as xs:string) {
   dots.delete:dbSwitch($dbName),
   dots.delete:registers($dbName, $option)
 };
 
+(:~
+: Updates the database "dots" by:
+: - updating the modification timestamp,
+: - decrementing the total number of projects,
+: - removing the <member> entry corresponding to the given database name.
+: @param  $dbName name of the project database to remove from the registry.
+: @return updates the <dbSwitch> document in the "dots" database.
+:)
 declare %private updating function dots.delete:dbSwitch($dbName as xs:string) {
   let $dbDots := db:get($G:dots)/dbSwitch
   let $totalProjects := $dbDots//totalProjects
@@ -30,6 +49,12 @@ declare %private updating function dots.delete:dbSwitch($dbName as xs:string) {
   )
 };
 
+(:~
+: Deletes the DoTS registers or the entire database depending on the option.
+: @param  $dbName name of the database to operate on.
+: @param  $option if "true", deletes the full database. Otherwise, only the registers are deleted.
+: @return executes deletion operations accordingly.
+:)
 declare %private updating function dots.delete:registers($dbName as xs:string, $option as xs:string) {
   if ($option = "true") then (
     db:drop($dbName)