docs: добавь поясняющие комментарии к модулям и инструментам

python/tests/test_altera_logic.py

@@ -1,3 +1,12 @@
+# Проверки altera_logic: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_rtl_info_and_first_configuration_vector
+#   test_error_response_is_short_even_for_info
+#   test_partial_response_times_out_without_retry
+#   test_demo_export_uses_capture_rate_not_current_ui_settings
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 """Golden RTL vectors through the Python FFI (no Python production codec)."""
 import tempfile
 import unittest

python/tests/test_altera_stream.py

@@ -1,3 +1,13 @@
+# Проверки altera_stream: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_can_uart_identical_and_duplicates
+#   test_gap_old_session_and_counter_wrap
+#   test_malformed_filter_crc_and_recovery
+#   test_bounded_history_and_export
+#   test_sparse_trace_does_not_connect_across_lost_samples
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 import tempfile
 import unittest
 from pathlib import Path

python/tests/test_devboard_v1.py

@@ -1,3 +1,10 @@
+# Проверки devboard_v1: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_parse_can_and_rs485_lines
+#   test_commands_are_firmware_compatible_and_lf_terminated
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 from protocan.devboard_v1 import BoardFrame, command_setup, command_transmit, parse_frame_line
 
 

python/tests/test_dslogic_trigger.py

@@ -1,3 +1,13 @@
+# Проверки dslogic_trigger: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_invalid_modes_and_disabled_conditions
+#   test_simple_maps_physical_channels_and_stream_position
+#   test_stage_count_logic_and_masks_match_driver_abi
+#   test_serial_mapping_and_data_channel_validation
+#   test_driver_errors_propagate
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 import unittest
 from dataclasses import replace
 from unittest.mock import Mock

python/tests/test_firmware_clients.py

@@ -1,3 +1,16 @@
+# Проверки firmware_clients: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_android_packet_layout_and_crc
+#   test_only_reserved_tail_may_be_missing
+#   test_tms_word_offsets_and_odd_final_byte_readback
+#   test_peripheral_flashing_and_verification
+#   test_load_only_never_writes_flash
+#   test_invalid_targets_fail_before_transmission
+#   test_legacy_can_full_transaction_and_retransmission
+#   test_can_rejects_unsent_blocks_wrong_slot_and_foreign_session
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 """Android wire compatibility and complete host-side flashing transactions."""
 from dataclasses import replace
 from types import SimpleNamespace

python/tests/test_firmware_database.py

@@ -1,3 +1,17 @@
+# Проверки firmware_database: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_publish_read_and_download_round_trip_and_idempotency
+#   test_failed_image_verification_never_writes_catalog
+#   test_rebuilt_image_keeps_old_asset_and_manifest_on_conflict
+#   test_preflight_is_offline
+#   test_missing_release_is_created
+#   test_download_size_limit_and_catalog_readback_failure
+#   test_bad_download_cleans_staging_and_rejects_unsafe_filename
+#   test_https_credentials_do_not_follow_cross_origin_redirect
+# Остальные сценарии продолжают эти проверки ниже в том же файле.
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 from __future__ import annotations
 
 import base64

python/tests/test_firmware_publish.py

@@ -1,3 +1,12 @@
+# Проверки firmware_publish: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_publication_validates_file_and_metadata
+#   test_entry_and_tag_are_deterministic
+#   test_update_preserves_sections_and_replaces_same_release
+#   test_legacy_array_is_migrated_without_data_loss
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 from __future__ import annotations
 
 import tempfile

python/tests/test_generator_data.py

@@ -1,3 +1,10 @@
+# Проверки generator_data: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_processing_csv_roundtrip_into_generator
+#   test_samples_recipe_and_resampling
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 """Waveform data helpers run independently of SETGUI and Qt."""
 import io
 import json

python/tests/test_legacycan.py

@@ -1,3 +1,11 @@
+# Проверки legacycan: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_catalog_matches_legacy_projects
+#   test_rotating_three_word_codec_and_bank
+#   test_address_in_identifier_codec_and_command
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 from protocan.legacycan import (
     LegacyCanFormat, LegacyCanSource, PROJECTS, apply_packet, decode,
     empty_register_bank, encode_command, encode_write, signed_word,

python/tests/test_logic_analyzer_analysis.py

@@ -1,3 +1,18 @@
+# Проверки logic_analyzer_analysis: фиксируют ожидаемое поведение на воспроизводимых входных
+# данных.
+# Сценарии для навигации по файлу:
+#   test_uart_byte_values_inverted_and_parity
+#   test_uart_errors_are_not_accepted_as_set_frames
+#   test_set_ping_bridge_crc_and_resynchronization
+#   test_pm35_request_and_special_response
+#   test_uart_end_flush_and_gap
+#   test_crc15_known_check_value
+#   test_can_standard_extended_remote_and_nack
+#   test_can_crc_error_recovery_and_application
+# Остальные сценарии продолжают эти проверки ниже в том же файле.
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 from array import array
 from collections import Counter
 from pathlib import Path

python/tests/test_logic_analyzer_dslogic.py

@@ -1,3 +1,18 @@
+# Проверки logic_analyzer_dslogic: фиксируют ожидаемое поведение на воспроизводимых входных
+# данных.
+# Сценарии для навигации по файлу:
+#   test_cross_words_preserve_physical_channels_boundary_edges_and_tail
+#   test_padding_is_not_imported_as_samples
+#   test_empty_truncated_wrong_mapping_and_cancel
+#   test_validation_rejects_old_driver_and_invalid_parameters
+#   test_host_does_not_inherit_frozen_gui_bootloader_state
+#   test_real_process_scan
+#   test_stop_is_graceful_and_imports_result
+#   test_cancel_reaps_process_and_discards_result
+# Остальные сценарии продолжают эти проверки ниже в том же файле.
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 from dataclasses import replace
 from io import BytesIO
 import json

python/tests/test_logic_analyzer_files.py

@@ -1,3 +1,16 @@
+# Проверки logic_analyzer_files: фиксируют ожидаемое поведение на воспроизводимых входных
+# данных.
+# Сценарии для навигации по файлу:
+#   test_csv_preserves_irregular_time_and_channel_names
+#   test_dsview_csv_metadata_and_units
+#   test_csv_rejects_invalid_data
+#   test_sal_chunks_levels_and_long_runs
+#   test_sal_rejects_truncated_and_unknown_version
+#   test_dsl_sparse_channels_blocks_and_padding
+#   test_cancelled_import
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 import csv
 import json
 from pathlib import Path

python/tests/test_logic_analyzer_saleae.py

@@ -1,3 +1,14 @@
+# Проверки logic_analyzer_saleae: фиксируют ожидаемое поведение на воспроизводимых входных
+# данных.
+# Сценарии для навигации по файлу:
+#   test_constant_channel_tail_and_sparse_channel_numbers
+#   test_reject_bad_binary_and_cancel
+#   test_settings_validation
+#   test_stop_exports_and_closes_exactly_once
+#   test_cancel_stops_without_export_and_failure_closes
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 from dataclasses import replace
 from pathlib import Path
 import struct

python/tests/test_logic_csv_import.py

@@ -1,3 +1,16 @@
+# Проверки logic_csv_import: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_regular_samples_preserve_levels_and_names
+#   test_sparse_transitions_preserve_short_pulses_across_blocks
+#   test_initial_snapshot_need_not_be_on_edge_clock
+#   test_comments_tab_delimiter_and_negative_origin
+#   test_bad_csv_leaves_no_output
+#   test_output_is_not_overwritten_and_size_limit_precedes_expansion
+#   test_cancel_during_packing_cleans_temporary_output
+#   test_changed_source_rejected_before_publication
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 from decimal import Decimal
 from pathlib import Path
 import tempfile

python/tests/test_periph28335.py

@@ -1,3 +1,11 @@
+# Проверки periph28335: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_read_request_matches_delphi_byte_order
+#   test_write_and_command_use_register_127
+#   test_bits_keep_original_lsb_first_order
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 from protocan.periph28335 import (
     bits_lsb_first, build_command, build_read_registers,
     build_write_register, crc16_modbus, word_from_bits,

python/tests/test_plot.py

@@ -1,3 +1,12 @@
+# Проверки plot: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_shared_numeric_fixtures
+#   test_markers_stay_in_data_coordinates_and_cross
+#   test_invalid_numeric_inputs_do_not_escape_to_painter
+#   test_locked_viewport_and_decibel_delta
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 """Cross-port contract: Python/ctypes and Kotlin/JNI consume the same fixtures."""
 import ctypes
 import json

python/tests/test_plot_formula.py

@@ -1,3 +1,11 @@
+# Проверки plot_formula: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_all_methods_match_native_values_on_irregular_and_duplicate_knots
+#   test_polynomial_model_with_fewer_output_samples_than_coefficients
+#   test_source_line_and_formula_use_displayed_origin
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 """Formula coefficients must reproduce the native reconstruction, not a refit."""
 import unittest
 from set_devices.signal_reconstruction import reconstruct

python/tests/test_plot_processing.py

@@ -1,3 +1,14 @@
+# Проверки plot_processing: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_snapshot_copies_mutable_samples_and_excludes_hidden_and_digital
+#   test_all_methods_use_same_contract_and_keep_source
+#   test_window_is_inclusive_and_never_extrapolates
+#   test_sparse_spline_and_noisy_polynomial_work_in_shared_pipeline
+#   test_csv_respects_explicit_axis_domain_and_units
+#   test_request_tracks_selected_channel_units_source_and_window
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 """Portable processing contract: no Qt or application imports."""
 import csv
 import io

python/tests/test_plot_processing_qt.py

@@ -1,3 +1,18 @@
+# Проверки plot_processing_qt: фиксируют ожидаемое поведение на воспроизводимых входных
+# данных.
+# Сценарии для навигации по файлу:
+#   test_all_methods_accumulate_and_parameter_changes_keep_results
+#   test_repeated_request_does_not_duplicate_curve
+#   test_repeated_fft_workers_keep_gui_owned_signal_emitters
+#   test_switching_channel_preserves_results_and_invalidates_only_changed_source
+#   test_navigation_during_second_calculation_preserves_both_results
+#   test_failed_calculation_keeps_previous_curve
+#   test_hidden_source_preserves_result_but_changed_samples_invalidate_it
+#   test_source_units_and_blocking_invalidate_result
+# Остальные сценарии продолжают эти проверки ниже в том же файле.
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 """Reusable Qt adapter tests, runnable with PySide2 or PySide6, without a GUI app repo."""
 import os
 os.environ.setdefault("QT_QPA_PLATFORM", "offscreen")

python/tests/test_setprotocol_can.py

@@ -1,3 +1,11 @@
+# Проверки setprotocol_can: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_can_id_roundtrip
+#   test_segmented_setp_frame_roundtrip
+#   test_reassembler_rejects_wrong_sequence
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 from setprotocol import Frame, FrameFlag, MessageType, build_frame, decode_datagram
 from setprotocol.can import CanAddress, CanFrame, CanReassembler, segment
 

python/tests/test_shared_library_boundary.py

@@ -1,3 +1,11 @@
+# Проверки shared_library_boundary: фиксируют ожидаемое поведение на воспроизводимых входных
+# данных.
+# Сценарии для навигации по файлу:
+#   test_cores_import_with_gui_and_qt_blocked
+#   test_no_reverse_imports_in_sources
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 """Shared libraries must import without the desktop application or Qt."""
 import os
 from pathlib import Path

python/tests/test_spectrum.py

@@ -1,3 +1,16 @@
+# Проверки spectrum: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_fft_matches_independent_direct_dft
+#   test_all_windows_preserve_bin_centered_peak_amplitude
+#   test_dc_and_nyquist_are_not_doubled
+#   test_windows_suppress_far_leakage_and_flattop_recovers_off_bin_amplitude
+#   test_filters_attenuate_expected_bands
+#   test_timestamp_rate_not_requested_rate_and_jitter_interpolation
+#   test_rejects_gaps_duplicates_bad_values_and_cutoffs
+#   test_size_limits_tail_selection_and_inputs_unchanged
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 import cmath
 import ctypes
 import math

python/tests/test_tms_terminal_shared.py

@@ -1,3 +1,14 @@
+# Проверки tms_terminal_shared: фиксируют ожидаемое поведение на воспроизводимых входных
+# данных.
+# Сценарии для навигации по файлу:
+#   test_ping_and_poke_vectors
+#   test_test_all_vector
+#   test_response_accepts_only_missing_reserved_bytes
+#   test_rejects_out_of_range_before_native_conversion
+#   test_uart_response_ignores_noise_and_preliminary_ack
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 """Wire vectors shared with Android and the native TMS2812 host test."""
 import pytest
 from protocan import tms_terminal as tms

python/tests/test_trends.py

@@ -1,3 +1,16 @@
+# Проверки trends: фиксируют ожидаемое поведение на воспроизводимых входных данных.
+# Сценарии для навигации по файлу:
+#   test_multiplier_and_iq_scale_display_and_old_json_defaults
+#   test_shared_kotlin_fixture_and_round_trip
+#   test_profile_specific_defaults
+#   test_invalid_import_and_types
+#   test_duplicates_and_limits
+#   test_addresses_and_signedness
+#   test_bounded_history
+#   test_actual_shared_c_core
+# Тестовые значения и подмены окружения относятся к проверке контракта; они не являются
+# настройками рабочего устройства.
+
 import ctypes
 import json
 import os