DOC: Update docstrings in markov/mc_tools.jl to follow style guide - #323

Merged

oyamad merged 5 commits into

copilot/fix-322

Sep 22, 2025

Copilot AI commented Sep 21, 2025 •

edited

Loading

Contributor

Updates all docstrings in src/markov/mc_tools.jl to follow the project's docstring style guide as specified in .github/copilot-instructions.md.

Changes Made

Style Guide Compliance

Function signatures: Added four-space indented function signatures at the beginning of all function docstrings
Section headers: Changed from old-style ##### Header format to the new # Header format
Parameter formatting: Updated parameter descriptions to use consistent formatting (no space before colon, periods at end)
Blank lines: Added appropriate spacing between section headers and content

Content Corrections

Spelling fixes: Corrected "convertion" → "conversion" and "reccurent" → "recurrent"
Escape character fix: Fixed \\sum back to \sum (removed extra escape character)

Preserved Original Formatting

@doc doc syntax: Maintained original @doc doc syntax for gth_solve and stationary_distributions functions
Multiline descriptions: Preserved original linebreaks in function descriptions and parameter lists where they enhance readability

Functions Updated

The following docstrings were updated to the new format:

MarkovChain struct
gth_solve and gth_solve! functions
n_states, recurrent_classes, communication_classes functions
is_irreducible, is_aperiodic, period functions
stationary_distributions function
simulate, simulate!, simulate_indices, simulate_indices! functions
Helper functions like todense

Quality Assurance

Documentation builds successfully with no parsing errors
All validation scenarios pass, confirming functionality is preserved
Changes are minimal and surgical, focusing only on docstring formatting
No functional code changes were made

The updated docstrings now provide consistent, professional formatting while maintaining all technical accuracy and ensuring continued functionality of the QuantEcon.jl package.

Fixes #322.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.


          Initial plan

369d8c9

Copilot AI assigned Copilot and oyamad

Copilot started work on behalf of oyamad

September 21, 2025 05:30

View session


          Update docstrings in markov/mc_tools.jl to follow style guide

0fa468a

Co-authored-by: oyamad <7353083+oyamad@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] DOC: Update docstrings in markov/mc_tools.jl~~ DOC: Update docstrings in markov/mc_tools.jl to follow style guide

Copilot finished work on behalf of oyamad

September 21, 2025 05:42

Copilot AI requested a review from oyamad

September 21, 2025 05:42

oyamad requested changes

View reviewed changes

oyamad left a comment

Member

@copilot Revert the removals of linebreaks.

src/markov/mc_tools.jl

                   print(io, mc.p)
               end
-              @doc doc"""

oyamad Sep 21, 2025

Member

@copilot Do not remove @doc doc.
And do not add an escape character \ to \sum.

Copilot AI Sep 21, 2025

Contributor Author

Restored @doc doc syntax and fixed \sum (removed extra escape character) in commit 0f7ece3. The original formatting has been preserved.

src/markov/mc_tools.jl Outdated

-                classes of `mc`.
+              # Returns
+              - `::Vector{Vector{Int}}`: Vector of vectors that describe the recurrent classes of `mc`.

oyamad Sep 21, 2025

Member

@copilot Do not alter the linebreaks.

Copilot AI Sep 21, 2025

Contributor Author

Restored original linebreaks for recurrent_classes function in commit 0f7ece3.

src/markov/mc_tools.jl Outdated

-                classes of `mc`.
+              # Returns
+              - `::Vector{Vector{Int}}`: Vector of vectors that describe the communication classes of `mc`.

oyamad Sep 21, 2025

Member

@copilot Do not alter the linebreaks.

Copilot AI Sep 21, 2025

Contributor Author

Restored original linebreaks for communication_classes function in commit 0f7ece3.

src/markov/mc_tools.jl Outdated

-                `Int` (and equal to `T` otherwise).
+              # Returns
+              - `stationary_dists::Vector{Vector{T1}}`: Vector of vectors that represent stationary distributions, where the element type `T1` is `Rational` if `T` is `Int` (and equal to `T` otherwise).

oyamad Sep 21, 2025

Member

@copilot Do not alter the linebreaks.

Copilot AI Sep 21, 2025

Contributor Author

Restored original linebreaks for stationary_distributions function in commit 0f7ece3.

src/markov/mc_tools.jl Outdated

-              - `X::Vector` : Vector containing the sample path, with length
-                ts_length
+              - `X::Vector`: Vector containing the sample path, with length ts_length.

oyamad Sep 21, 2025

Member

@copilot Do not alter the linebreaks.

Copilot AI Sep 21, 2025

Contributor Author

Restored original linebreaks for simulate function in commit 0f7ece3.

src/markov/mc_tools.jl Outdated

-              same as the type of the state values of `mc`
-              - `mc::MarkovChain` : MarkovChain instance.
-              - `;init=rand(1:n_states(mc))` : Can be one of the following
+              - `X::Matrix`: Preallocated matrix to be filled with sample paths of the Markov chain `mc`. The element types in `X` should be the same as the type of the state values of `mc`.

oyamad Sep 21, 2025

Member

@copilot Do not alter the linebreaks.

Copilot AI Sep 21, 2025

Contributor Author

Restored original linebreaks for simulate! function in commit 0f7ece3.

src/markov/mc_tools.jl Outdated

-                  - vector: cycle through the elements, applying each as an
-                    initial condition until all columns have an initial condition
-                    (allows for more columns than initial conditions)
+                  - vector: cycle through the elements, applying each as an initial condition until all columns have an initial condition (allows for more columns than initial conditions)

oyamad Sep 21, 2025

Member

@copilot Do not alter the linebreaks.

Copilot AI Sep 21, 2025

Contributor Author

Restored original linebreaks for simulate! function parameter descriptions in commit 0f7ece3.

src/markov/mc_tools.jl Outdated

-              - `X::Vector{Int}` : Vector containing the sample path, with length
-                ts_length
+              - `X::Vector{Int}`: Vector containing the sample path, with length ts_length.

oyamad Sep 21, 2025

Member

@copilot Do not alter the linebreaks.

Copilot AI Sep 21, 2025

Contributor Author

Restored original linebreaks for simulate_indices function in commit 0f7ece3.

src/markov/mc_tools.jl Outdated

-              of the sample paths of the Markov chain `mc`.
-              - `mc::MarkovChain` : MarkovChain instance.
-              - `;init=rand(1:n_states(mc))` : Can be one of the following
+              - `X::Matrix{Int}`: Preallocated matrix to be filled with indices of the sample paths of the Markov chain `mc`.

oyamad Sep 21, 2025

Member

@copilot Do not alter the linebreaks.

Copilot AI Sep 21, 2025

Contributor Author

Restored original linebreaks for simulate_indices! function in commit 0f7ece3.

src/markov/mc_tools.jl Outdated

-                  - vector: cycle through the elements, applying each as an
-                    initial condition until all columns have an initial condition
-                    (allows for more columns than initial conditions)
+                  - vector: cycle through the elements, applying each as an initial condition until all columns have an initial condition (allows for more columns than initial conditions)

oyamad Sep 21, 2025

Member

@copilot Do not alter the linebreaks.

Copilot AI Sep 21, 2025

Contributor Author

Restored original linebreaks for simulate_indices! function parameter descriptions in commit 0f7ece3.

Copilot started work on behalf of oyamad

September 21, 2025 05:52

View session

oyamad added the docs label


          Revert formatting changes based on feedback: restore @doc doc, fix \s…

0f7ece3

…um, restore linebreaks

Co-authored-by: oyamad <7353083+oyamad@users.noreply.github.com>

Copilot AI commented Sep 21, 2025

Contributor Author

@copilot Revert the removals of linebreaks.

Reverted the removal of linebreaks in commit 0f7ece3. The original multiline formatting has been restored for function descriptions and parameter lists.

Copilot AI requested a review from oyamad

September 21, 2025 05:59

Copilot finished work on behalf of oyamad

September 21, 2025 05:59

oyamad requested changes

View reviewed changes

oyamad left a comment

Member

@copilot Follow the instructions in .github/copilot-instructions.md!

Start with a four-space indented function signature showing the function name and key parameters
Use single # for section headers (not #####)

Copilot started work on behalf of oyamad

September 21, 2025 06:05

View session


          Follow style guide: add function signatures and use single # headers

1c2de1e

Co-authored-by: oyamad <7353083+oyamad@users.noreply.github.com>

Copilot AI commented Sep 21, 2025

Contributor Author

@copilot Follow the instructions in .github/copilot-instructions.md!

Start with a four-space indented function signature showing the function name and key parameters

Use single # for section...

Applied style guide formatting in commit 1c2de1e:

Added four-space indented function signatures to all function docstrings
Changed section headers from ##### to single # format
Maintained @doc doc syntax where originally present
Preserved multiline formatting in descriptions and parameter lists
Updated parameter formatting (no space before colon, periods at end)

Copilot AI requested a review from oyamad

September 21, 2025 06:11

Copilot stopped work on behalf of oyamad due to an error

September 21, 2025 06:11

Copilot has encountered an error. See logs for additional details.


          Fix formatting in mc_tools.jl import statement

45f91a8

oyamad marked this pull request as ready for review

September 21, 2025 06:29

oyamad approved these changes

View reviewed changes

oyamad added the ready label

oyamad merged commit 607e0c6 into master

10 checks passed

oyamad deleted the copilot/fix-322 branch

September 22, 2025 05:33

oyamad mentioned this pull request

Redo documentation #136

Closed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels