Unify documentation

[Vladyslav-Kuksiuk]

This PR unifies the documentation for the whole project.

[Copilot]

Pull request overview

This PR standardizes documentation across the project by rewriting/expanding Go doc comments (including struct-field comments), aligning comment style (Parameters/Returns blocks), and making small Markdown heading/whitespace adjustments. It also updates the repository’s agent skills documentation to codify the same documentation conventions.

Changes:

• Added/normalized Go doc comments across core packages (embedding/, fragmentation/, cli/, logging/, etc.), including per-field struct documentation.
• Updated parser/embedding-related comments to be more explicit about behavior, parameters, and return values.
• Minor Markdown cleanup (heading capitalization, trailing whitespace) and skill doc updates to reflect the unified style.

Reviewed changes

Copilot reviewed 52 out of 53 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
type/string_list.go	Adds parameter/return details to YAML unmarshalling docs.
type/named_path_list.go	Documents struct fields and YAML unmarshalling behavior.
showcase/showcase_test.go	Adds field comments to test-case structs for clarity.
showcase/README.md	Normalizes section heading capitalization.
README.md	Removes trailing whitespace in the Run section.
main.go	Renames a process description term in the main doc comment.
logging/logger.go	Documents Handler fields and logging helper behaviors.
logging/error.go	Adds parameter/return details for error formatting docs.
indent/indent.go	Reworks doc comments to the unified Parameters/Returns style.
indent/indent_test.go	Adds a suite-level test function comment.
fragmentation/resolver.go	Documents resolver cache structures and public APIs.
fragmentation/partition.go	Documents partition fields and selection behavior.
fragmentation/lookup.go	Adds marker constant docs and clarifies fragment lookup docs.
fragmentation/fragmentation.go	Clarifies fragmentation API docs and internal helper intent.
fragmentation/fragmentation_test.go	Adds suite/function comments for test helpers.
fragmentation/fragment.go	Documents fragment fields and rendering behavior.
fragmentation/fragment_builder.go	Documents builder fields and method behavior/constraints.
fragmentation/encoding.go	Clarifies the encoding error’s Error() documentation.
fragmentation/cache.go	Documents cache fields and intended invariants.
files/files.go	Updates docs to describe file/dir existence helpers and return semantics.
files/files_test.go	Adds a suite-level test function comment.
embedding/processor.go	Expands processor API docs, especially return semantics.
embedding/parsing/xml_parse.go	Clarifies <embed-code> parsing docs and supported attributes.
embedding/parsing/state.go	Standardizes state interface documentation.
embedding/parsing/start.go	Updates StartState docs to unified style.
embedding/parsing/regular_line.go	Clarifies ordinary Markdown line handling and helper intent.
embedding/parsing/pattern.go	Documents pattern structure and matcher behavior.
embedding/parsing/instruction.go	Documents instruction fields and pattern error structures.
embedding/parsing/instruction_token.go	Documents parse error structs and token state behavior.
embedding/parsing/instruction_test.go	Adds comments to test param struct and helper functions.
embedding/parsing/finish.go	Standardizes FinishState doc comments.
embedding/parsing/context.go	Documents parsing context fields and helper methods.
embedding/parsing/constants.go	Documents parser state variables and roles.
embedding/parsing/code_sample_line.go	Clarifies behavior for embedded-source lines in fences.
embedding/parsing/code_fence_start.go	Clarifies opening fence recognition and state recording.
embedding/parsing/code_fence_end.go	Clarifies closing fence recognition and rendering behavior.
embedding/parsing/blank_line.go	Standardizes blank-line state docs between instruction and fence.
embedding/orchestration.go	Documents multi-file embed/check orchestration functions.
embedding/error.go	Documents processing error wrapper fields and methods.
embedding/embedding_test.go	Adds comments to suite and test helper functions.
embedding/commentfilter/visual_basic.go	Documents Visual Basic comment filter API.
embedding/commentfilter/mode.go	Documents comment-mode parsing semantics.
embedding/commentfilter/marker_comment_filter.go	Documents syntax marker structs and filter state.
embedding/commentfilter/filter.go	Documents public filtering API and interface contract.
embedding/commentfilter/config.go	Documents filter registry entries and supported modes.
configuration/configuration.go	Updates package/type descriptions to “embed-code settings”.
cli/cli.go	Documents CLI config structs/fields and key exported functions.
cli/cli_validation.go	Converts header comment style and expands function docs.
cli/cli_test.go	Converts header comment style and adds helper doc comments.
.agents/skills/writer/SKILL.md	Renames headings and adds explicit Go doc style guidance.
.agents/skills/review-docs/SKILL.md	Renames headings and adds explicit struct-field doc requirements.
.agents/skills/go-tester/SKILL.md	Renames heading to match unified style.
.agents/skills/go-engineer/SKILL.md	Updates documentation expectations (functions + struct fields).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Oleg-Melnik]

@Vladyslav-Kuksiuk LGTM with Copilot’s comments addressed before merging.