refactor: streamline segment parsing and cleanup redundant functions

- Removed unused `parse_segment_dir` implementation.
- Simplified segment-saving logic and enhanced schema population.
- Improved docstrings for clarity and added multiline description parsing support.
- Added warnings for duplicate segment tags.
- Made generated files explicitly marked as auto-generated.

Author: nerdoc