Flesh out 1-line docstrings for key types#584
Merged
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This pull request expands and refines docstrings across InfrastructureSystems’ core abstract types, container/manager types, time-series interfaces, and serialization utilities to improve API clarity and discoverability for downstream Sienna packages.
Changes:
- Expanded docstrings for core abstract types (components, device parameters, supplemental attributes) and time-series metadata/data abstractions.
- Documented container and manager responsibilities/relationships (
SystemData,Components,TimeSeriesManager,SupplementalAttributeManager, associations, UUID tracking). - Improved serialization/deserialization docstrings and cross-references (
to_json,from_json,serialize,deserialize).
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| src/time_series_structs.jl | Added docstring clarifying what can own time series data/metadata. |
| src/time_series_manager.jl | Documented TimeSeriesManager role and clear_time_series! behavior. |
| src/system_data.jl | Expanded SystemData and related API docstrings (masking, serialization prep, add/rename, supplemental attributes). |
| src/supplemental_attribute_manager.jl | Added manager-level docstring and clarified iterator/filter documentation. |
| src/supplemental_attribute_associations.jl | Added high-level docstring describing the SQLite-backed association store. |
| src/serialization.jl | Reworked to_json/from_json/serialize/deserialize docstrings and “See also” links. |
| src/internal.jl | Documented SharedSystemReferences and clarified internal storage responsibilities. |
| src/InfrastructureSystems.jl | Expanded docstrings for key abstract types and their required/optional interfaces. |
| src/containers.jl | Added docstring for the top-level container abstraction. |
| src/components.jl | Improved documentation for Components container and add_component! behavior/errors. |
| src/component_uuids.jl | Documented ComponentUUIDs purpose for supplemental attribute association tracking. |
| src/component_container.jl | Refined ComponentContainer interface docstring and references. |
| src/abstract_time_series.jl | Expanded docstrings for time-series metadata/data abstractions and forecast/static metadata. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #584 +/- ##
==========================================
- Coverage 78.87% 78.86% -0.01%
==========================================
Files 75 75
Lines 6656 6649 -7
==========================================
- Hits 5250 5244 -6
+ Misses 1406 1405 -1
Flags with carried forward coverage won't be shown. Click here to find out more.
🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request significantly improves the documentation and clarity of core abstract types, containers, and serialization interfaces in the InfrastructureSystems codebase. The main focus is on rewriting and expanding docstrings to clarify the purpose, usage, and relationships of key types, as well as improving references and discoverability for users and downstream developers.
The most important changes are:
Core Abstract Types and Components:
InfrastructureSystemsType,InfrastructureSystemsComponent,DeviceParameter, andSupplementalAttribute, detailing required interfaces, usage patterns, and relationships between types. Added extensive cross-references to related types and methods.TimeSeriesMetadata,ForecastMetadata,StaticTimeSeriesMetadata,TimeSeriesData), specifying their roles, construction, and usage in the system. [1] [2] [3]Containers and Managers:
ComponentContainer,Components,InfrastructureSystemsContainer, andSystemData, explaining their responsibilities, interfaces, and member access patterns. [1] [2] [3] [4]SupplementalAttributeManagerand its association-tracking mechanism, clarifying how supplemental attributes are managed and linked to components. [1] [2]Serialization and Deserialization:
to_json,from_json,serialize, anddeserializefunctions, clarifying their usage, expected arguments, and relationships to each other. Added detailed "See also" references for easier navigation. [1] [2] [3] [4] [5]Internal and Utility Types:
ComponentUUIDs(for tracking component associations) andSharedSystemReferences(for wiring system-level managers into components and attributes). [1] [2]General Improvements:
add_component!.These changes collectively make the codebase much more approachable for new contributors and downstream package authors, and improve the reliability of API usage through clearer documentation.