diff --git a/docs/audits/documentation_inventory.md b/docs/audits/documentation_inventory.md index 8260a5d..c145a4b 100644 --- a/docs/audits/documentation_inventory.md +++ b/docs/audits/documentation_inventory.md @@ -619,6 +619,7 @@ Translation of historical evidence must preserve the historical checkpoint exact - DOCUMENTATION_INVENTORY_AUDIT=PASS_WITH_FINDINGS - DOCUMENTATION_FINDING_REMEDIATION=PASS - DOCUMENTATION_LANGUAGE_NORMALIZATION=IN_PROGRESS -- SOURCE_COMMENT_AUDIT=NEXT -- PRODUCT_DEFINITION=NOT_STARTED +- SOURCE_COMMENT_AUDIT=PASS +- SOURCE_COMMENT_REMEDIATION=PASS +- PRODUCT_DEFINITION=NEXT - PROMPT_TREE=NOT_STARTED diff --git a/docs/audits/source_comment_inventory.md b/docs/audits/source_comment_inventory.md new file mode 100644 index 0000000..1939f4e --- /dev/null +++ b/docs/audits/source_comment_inventory.md @@ -0,0 +1,99 @@ +# Lardon3D — Source Comment Audit + +## Status + +```text +SOURCE_COMMENT_AUDIT=PASS +SOURCE_COMMENT_REMEDIATION=PASS +SOURCE_COMMENT_SCOPE=include/lardon3d/** + src/** +SOURCE_COMMENT_LANGUAGE=ENGLISH +SOURCE_CODE_BEHAVIOR_CHANGED=NO +``` + +The audit covered 148 C/C++ source/header files under `include/lardon3d/**` and `src/**`. + +The initial static inventory reported: + +```text +comment blocks 807 +raw non-English lexical candidates 33 +actual French comment blocks 29 +English false positives 4 +stale-contract candidates 0 +raw unannotated-public declarations 324 +``` + +## Remediation + +All 29 actual French source comments were translated to English. + +The four raw language-detector false positives were already English and were left unchanged. + +The remediation touched comments only. A file-level lexical comparison removed comments entirely and verified that every non-comment source +byte remained identical before and after the declared replacements. + +No executable UI/error string was changed in this pass. UI language is a separate explicitly scoped +implementation pass. + +## Stale and misleading comments + +The lexical stale-contract pass found zero candidate comments. + +No scientific threshold, schema version, Task Kind, resource contract, persistence identity or FROZEN +boundary was changed by this audit. + +## Public API adjacency heuristic + +The first inventory reported 324 public declarations without an immediately adjacent comment. + +That number is **informational only**, not 324 defects. + +The repository Source Comment Contract requires comments where WHY, CONTRACT, INVARIANT, OWNERSHIP, +IDENTITY, persistence ordering, restart, cancellation, concurrency, resource accounting or a FROZEN +boundary is non-obvious. It does not require one redundant comment for every getter, thin wrapper, +paired create/load/list function or declaration already covered by a surrounding contract block. + +Therefore absence of an adjacent comment alone is not a valid +`UNDER_COMMENTED`/`SEVERELY_UNDER_COMMENTED` finding. + +Future audits must review semantic contract coverage rather than using declaration adjacency as a +blanket failure criterion. + +## Source Comment Contract + +Production source comments: + +- are English; +- explain non-obvious WHY/CONTRACT/INVARIANT facts; +- preserve ownership and lifetime boundaries; +- preserve persistence/restart ordering; +- preserve concurrency/resource-accounting boundaries; +- preserve scientific identity and FROZEN constraints; +- do not paraphrase obvious code line-by-line; +- are updated when behavior changes. + +## Validation + +The remediation runner requires: + +```text +branch = docs-audit +no unrelated worktree changes +all expected old comments match exactly once +file-level source with all comments removed remains byte-for-byte identical +no strong French-comment candidate remains +git diff --check passes +``` + +## Phase state + +```text +DOCUMENTATION_FINDING_REMEDIATION=PASS +DOCUMENTATION_LANGUAGE_NORMALIZATION=IN_PROGRESS + +SOURCE_COMMENT_AUDIT=PASS +SOURCE_COMMENT_REMEDIATION=PASS + +PRODUCT_DEFINITION=NEXT +PROMPT_TREE=NOT_STARTED +``` diff --git a/include/lardon3d/candidate_pair_gen.h b/include/lardon3d/candidate_pair_gen.h index 6c00c34..13631c8 100644 --- a/include/lardon3d/candidate_pair_gen.h +++ b/include/lardon3d/candidate_pair_gen.h @@ -9,9 +9,9 @@ #include typedef struct { - uint32_t generated_count; // paires nouvellement créées - uint32_t skipped_count; // paires déjà existantes (idempotence) - uint32_t queried_count; // candidats retournés par le Visual Index + uint32_t generated_count; // newly created pairs + uint32_t skipped_count; // already existing pairs (idempotent reuse) + uint32_t queried_count; // candidates returned by the Visual Index } Lardon3DCandidatePairGenStats; Lardon3DVisualIndexResult lardon3d_candidate_pair_generate( diff --git a/include/lardon3d/import_task.h b/include/lardon3d/import_task.h index ad1d61a..fd53d9a 100644 --- a/include/lardon3d/import_task.h +++ b/include/lardon3d/import_task.h @@ -42,7 +42,7 @@ bool lardon3d_project_enqueue_image_import(Lardon3DAppState *state, uint64_t sca bool lardon3d_image_import_reconstruct(const Lardon3DTaskDurableSnapshot *snapshot, void *context, Lardon3DTaskKindBinding *binding); -/* Compatibilité TUI : handle léger sur une tâche de la queue, sans thread. */ +/* TUI compatibility: lightweight handle over a Queue Task, with no private thread. */ Lardon3DImportTask *lardon3d_import_task_create(void); bool lardon3d_import_task_start(Lardon3DImportTask *task, Lardon3DAppState *state, const char *source_directory); diff --git a/include/lardon3d/resource_governor.h b/include/lardon3d/resource_governor.h index 58e09b3..3cfc770 100644 --- a/include/lardon3d/resource_governor.h +++ b/include/lardon3d/resource_governor.h @@ -325,11 +325,11 @@ const char *lardon3d_resource_decision_name( Lardon3DResourcePressure lardon3d_resource_governor_pressure( Lardon3DResourceGovernor *governor ); -/* Enregistre les métriques d'un lot terminé pour l'adaptation dynamique - * de la taille des lots futurs. batch_size est le nombre d'éléments dont le - * traitement a été validé dans ce lot. peak_memory_bytes == 0 signifie que - * la mesure est inconnue et n'alimente jamais l'adaptation mémoire. Le buffer - * est borné (8 entrées par classe de tâche). Thread-safe. */ +/* Records metrics from one completed batch for dynamic adaptation of future + * batch sizes. batch_size is the number of items whose processing was validated + * in this batch. peak_memory_bytes == 0 means the measurement is unknown and + * never feeds memory adaptation. The buffer is bounded to 8 entries per Task + * class. Thread-safe. */ bool lardon3d_resource_governor_record_batch( Lardon3DResourceGovernor *governor, Lardon3DResourceTaskClass task_class, diff --git a/include/lardon3d/task.h b/include/lardon3d/task.h index e60f356..f674dfc 100644 --- a/include/lardon3d/task.h +++ b/include/lardon3d/task.h @@ -108,8 +108,8 @@ Lardon3DTask *lardon3d_task_create_typed( Lardon3DTaskUserdataDestroy userdata_destroy ); void lardon3d_task_destroy(Lardon3DTask *task); -/* Exécute le callback dans le thread appelant. Le callback est invoqué hors - * mutex de tâche; le contract d'exécution et l'état appartiennent à la tâche. +/* Executes the callback on the calling thread. The callback runs outside + * the Task mutex; the execution contract and state remain owned by the Task. */ bool lardon3d_task_start( Lardon3DTask *task, @@ -169,16 +169,16 @@ Lardon3DTask *lardon3d_task_restore_typed( void *userdata, Lardon3DTaskUserdataDestroy userdata_destroy ); -/* Une restauration typée réussie transfère userdata/userdata_destroy à la - * tâche. En cas d'échec, l'appelant en reste propriétaire. */ +/* A successful typed restore transfers userdata/userdata_destroy ownership + * to the Task. On failure, the caller retains ownership. */ bool lardon3d_task_kind_is_valid(const char *task_kind); bool lardon3d_task_kind( const Lardon3DTask *task, char task_kind[LARDON3D_TASK_KIND_CAPACITY], uint32_t *task_kind_version ); -/* Appelé au plus une fois, hors mutex de tâche et après libération de la - * réservation terminale. Le userdata de tâche reste vivant jusqu'au retour. */ +/* Invoked at most once, outside the Task mutex and after the terminal + * reservation is released. Task userdata remains alive until the callback returns. */ bool lardon3d_task_set_finished_callback( Lardon3DTask *task, Lardon3DTaskFinishedCallback callback, @@ -190,21 +190,20 @@ bool lardon3d_task_resource_estimate( const Lardon3DTask *task, Lardon3DResourceEstimate *estimate ); -/* L'exécution ne reçoit pas de politique d'admission : c'est au gouverneur de - * confirmer la réservation avant l'exécution. +/* Execution does not receive admission policy: the Governor must confirm + * the reservation before execution. */ bool lardon3d_task_execution_contract( const Lardon3DTask *task, Lardon3DTaskExecutionContract *contract ); -/* Libère la réservation courante, en obtient une nouvelle auprès du gouverneur - * et met à jour le contrat. À appeler uniquement depuis le callback en cours - * d'exécution. Une réponse WAIT du gouverneur est une indisponibilité - * temporaire : la fonction attend un changement de ressources puis retente - * l'admission sans échouer la tâche. Les bornes de lot se poursuivent après - * cette nouvelle admission. Retourne false si la tâche est annulée - * (TASK_CANCELLED), si le gouverneur répond REJECT ou en cas d'erreur interne - * (TASK_FAILED). */ +/* Releases the current reservation, obtains a new one from the Governor, + * and updates the execution contract. Call only from the currently executing + * callback. A Governor WAIT is temporary unavailability: this function waits + * for a resource change and retries admission without failing the Task. Batch + * bounds continue under the new admission. Returns false if the Task is + * cancelled (TASK_CANCELLED), the Governor returns REJECT, or an internal + * error fails the Task (TASK_FAILED). */ bool lardon3d_task_sequence_break( Lardon3DTask *task, Lardon3DResourceGovernor *governor, diff --git a/include/lardon3d/task_queue.h b/include/lardon3d/task_queue.h index a1481ab..817d492 100644 --- a/include/lardon3d/task_queue.h +++ b/include/lardon3d/task_queue.h @@ -42,10 +42,6 @@ typedef struct { * serialized worker. capacity bounds pending Tasks, not terminal history; the * Governor retains resource-admission ownership and must outlive the Queue. * - * File d'exécution bornée, à ordre d'attente FIFO avec sélection adaptative du - * premier travail admissible, et un seul worker: ownership d'ordonnancement et - * de backpressure seulement. L'admission des demandes reste au Governneur. - * * CONTRACT: after a successful add, the Queue owns Task and its userdata. Once * the Task is terminal and its finished callback has returned, the Queue keeps * only a snapshot and promptly destroys the real Task outside the Queue lock. @@ -73,8 +69,8 @@ Lardon3DTaskQueue *lardon3d_task_queue_create( * starts after destruction safe. NULL is accepted. Never call destroy * synchronously from a Task finished callback running on this Queue. */ void lardon3d_task_queue_destroy(Lardon3DTaskQueue *queue); -/* La file devient propriétaire de task uniquement en cas de succès. - * Bloquante : attend une place libre si la file est pleine. A zero Task ID is +/* The Queue takes ownership of task only on success. + * Blocking: waits for a free slot when the Queue is full. A zero Task ID is * assigned from a nonzero monotonic sequence and is never generated twice * during this Queue lifetime, including after terminal-history eviction or * removal. Once UINT64_MAX has been generated (or consumed by a restored @@ -85,8 +81,8 @@ bool lardon3d_task_queue_add( Lardon3DTask *task, uint64_t *task_id ); -/* Non-bloquante : retourne false si la file est pleine ou en arrêt. - La file devient propriétaire de task uniquement en cas de succès. */ +/* Non-blocking: returns false if the Queue is full or stopping. + The Queue takes ownership of task only on success. */ bool lardon3d_task_queue_try_add( Lardon3DTaskQueue *queue, Lardon3DTask *task, diff --git a/src/acquisition_campaign_task.cpp b/src/acquisition_campaign_task.cpp index 0dcc765..00fb082 100644 --- a/src/acquisition_campaign_task.cpp +++ b/src/acquisition_campaign_task.cpp @@ -397,9 +397,9 @@ bool run_impl(Lardon3DTask *t, void *p) { c->db, lardon3d_task_id(t), group_id, materialized_capture_id, group_id) != LARDON3D_PROJECT_DB_OK) return lardon3d_task_fail(t, "Rétention de Capture impossible."); - /* Limite de reprise acceptée: entre le retour de S3-E et cette rétention - * durable, une identité de capture ne peut pas être déduite à posteriori - * depuis les chemins/métadonnées/ID d'image. + /* Accepted recovery boundary: between S3-E returning and this durable + * retention, Capture identity cannot be reconstructed retroactively from + * paths, metadata, or image IDs. */ #ifdef LARDON3D_ACQUISITION_CAMPAIGN_TASK_TESTING const char *after_retention = diff --git a/src/resource_governor.c b/src/resource_governor.c index 9b81c72..604d874 100644 --- a/src/resource_governor.c +++ b/src/resource_governor.c @@ -1797,8 +1797,8 @@ record_batch_locked( metrics[head] = (Lardon3DBatchMetrics) { .batch_size = batch_size, .duration_ns = duration_ns, - /* Zéro est le marqueur persistant « mesure inconnue ». La boucle - * d'adaptation ignore explicitement ces échantillons. */ + /* Zero is the sentinel for an unknown measurement. The adaptation + * loop explicitly ignores these samples. */ .peak_memory_bytes = peak_memory_bytes, }; head = (head + 1) % LARDON3D_BATCH_METRICS_CAPACITY; @@ -1836,9 +1836,9 @@ adaptive_batch_limit( % LARDON3D_BATCH_METRICS_CAPACITY; const Lardon3DBatchMetrics *m = &governor->batch_metrics[class_index][idx]; if (m->batch_size > 0 && m->peak_memory_bytes > 0) { - /* Coût par élément le plus défavorable observé : une moyenne - * sous-estimerait le pic et laisserait un lot dépasser son - * budget. La stabilité de l'hôte prime sur le débit. */ + /* Use the worst observed per-item cost: an average would + * underestimate the peak and could let a batch exceed its + * budget. Host safety takes precedence over throughput. */ uint64_t per_item = m->peak_memory_bytes / m->batch_size + (m->peak_memory_bytes % m->batch_size != 0); if (per_item > measured_per_item) { @@ -1853,9 +1853,9 @@ adaptive_batch_limit( if (measured_per_item <= memory_bytes_per_item) { return static_batch; } - /* Éviter l'overflow de la multiplication : si static_batch est trop - * grand pour être multiplié sans débordement, on retourne 1 (le lot le - * plus conservateur possible) plutôt que de saturer à SIZE_MAX. */ + /* Avoid multiplication overflow: if static_batch is too large to + * multiply safely, return 1 (the most conservative batch) instead of + * saturating to SIZE_MAX. */ if (static_batch > UINT64_MAX / memory_bytes_per_item) { return 1; } @@ -3222,10 +3222,10 @@ evaluate_locked( ) ); } - /* Le lot maximal visé est corrigé par les métriques mesurées : c'est la - * nouvelle cible du contrat, pas une réduction faute de ressources. La - * correction ne descend jamais sous minimum_batch_size pour éviter un - * WAIT persistant. */ + /* Measured metrics adjust the target maximum batch: this becomes the + * contract target, not a reduction caused by current resource shortage. + * The adjustment never falls below minimum_batch_size, avoiding a + * persistent WAIT. */ size_t adapted_maximum = adaptive_batch_limit( governor, estimate->task_class, @@ -3626,7 +3626,7 @@ lardon3d_resource_governor_record_batch( return false; } if (batch_size == 0) { - /* No-op réussi : aucune métrique, aucun réveil inutile. */ + /* Successful no-op: no metrics and no unnecessary wake-up. */ return true; } (void)pthread_mutex_lock(&governor->mutex); diff --git a/src/task.c b/src/task.c index 93eaed3..261c78d 100644 --- a/src/task.c +++ b/src/task.c @@ -612,8 +612,8 @@ lardon3d_task_destroy(Lardon3DTask *task) "Annulation demandée."); (void)pthread_cond_broadcast(&task->condition); } else { - /* Une tâche locale jamais soumise peut être abandonnée sans - * publier une fausse annulation métier. */ + /* A local Task that was never submitted may be abandoned without + * publishing a false business-level cancellation. */ finish_locked(task, TASK_CANCELLED, "Tâche abandonnée."); task->finished_notified = true; } @@ -885,7 +885,7 @@ lardon3d_task_checkpoint(Lardon3DTask *task) } enum { - /* Attente bornée entre deux tentatives d'admission : 50 ms. */ + /* Bounded wait between admission attempts: 50 ms. */ LARDON3D_SEQUENCE_ADMISSION_WAIT_NS = 50000000ULL, }; @@ -931,7 +931,7 @@ lardon3d_task_sequence_break( (void)lardon3d_resource_governor_release(governor, previous); } for (;;) { - /* Vérifier pause et annulation avant chaque tentative d'admission. */ + /* Check pause and cancellation before every admission attempt. */ (void)pthread_mutex_lock(&task->mutex); while (task->pause_requested && !task->cancel_requested) { task->state = TASK_PAUSED; @@ -962,7 +962,7 @@ lardon3d_task_sequence_break( &next ); if (!admitted) { - /* Erreur interne : échec d'allocation ou d'instantané. */ + /* Internal error: allocation or resource-snapshot failure. */ if (next) { (void)lardon3d_resource_governor_release(governor, next); } @@ -1079,8 +1079,8 @@ lardon3d_task_sequence_break( (void)pthread_mutex_unlock(&task->mutex); return false; case LARDON3D_RESOURCE_WAIT: - /* Indisponibilité temporaire : ne pas échouer, attendre un - * changement de ressources puis retenter l'admission. */ + /* Temporary unavailability: do not fail the Task; wait for a + * resource change and retry admission. */ if (next) { (void)lardon3d_resource_governor_release(governor, next); } @@ -1091,7 +1091,7 @@ lardon3d_task_sequence_break( ); break; default: - /* Décision inconnue : erreur interne, ne jamais boucler. */ + /* Unknown decision: internal error; never loop on it. */ if (next) { (void)lardon3d_resource_governor_release(governor, next); } diff --git a/src/task_queue.c b/src/task_queue.c index 865360a..3efa2f3 100644 --- a/src/task_queue.c +++ b/src/task_queue.c @@ -290,9 +290,9 @@ unlink_pending(Lardon3DTaskQueue *queue, TaskNode *previous, TaskNode *node) } node->next_pending = NULL; --queue->pending_count; - /* Chaque retrait libère une place. Plusieurs producteurs peuvent dormir - * pendant que le worker retire plusieurs tâches avant qu'ils reprennent - * le mutex ; chacun de ces retraits doit donc produire un réveil. */ + /* Every removal frees one slot. Multiple producers may be asleep while + * the worker removes several Tasks before they reacquire the mutex, so + * every removal must signal one waiter. */ (void)pthread_cond_signal(&queue->not_full); } @@ -361,12 +361,11 @@ destroy_retired(TaskNode *retired) } } -/* Parcourt la file d'attente dans son ordre FIFO et sélectionne la première - * tâche admissible; une attente de ressources peut donc laisser passer une - * tâche antérieure sans lui faire perdre sa place dans la file. - * Les tâches terminales ou refusées sont retirées de la file d'attente. - * Une tâche en attente de ressources reste en file et sera réévaluée. - * Retourne NULL si aucune tâche ne peut démarrer immédiatement. */ +/* Scans pending Tasks in FIFO order and selects the first admissible one. + * A resource WAIT may therefore let a later Task run without removing the + * waiting Task from its position. Terminal or rejected Tasks are removed. + * A resource-waiting Task remains queued for later re-evaluation. + * Returns NULL when no Task can start immediately. */ static TaskNode * select_admissible( Lardon3DTaskQueue *queue, @@ -541,10 +540,10 @@ queue_worker(void *context) ); } } - /* La tâche peut avoir libéré et re-réservé via sequence_break pendant - * son callback. Dans ce cas la réservation d'origine est déjà libérée - * et cet appel est sans effet ; la réservation courante de la tâche a - * été libérée par lardon3d_task_start. */ + /* The Task may have released and re-reserved through sequence_break + * during its callback. In that case the original reservation is + * already released and this call is a no-op; lardon3d_task_start + * released the Task's current reservation. */ if (reservation) { (void)lardon3d_resource_governor_release( queue->governor, @@ -763,7 +762,7 @@ lardon3d_task_queue_destroy(Lardon3DTaskQueue *queue) free(queue); } -/* Appelée sous le mutex queue. Ne signale pas not_empty sur échec. */ +/* Called with the Queue mutex held. Does not signal not_empty on failure. */ static bool enqueue_locked( Lardon3DTaskQueue *queue,