Docs - #10
Merged
Merged
Conversation
Add a README "Methods & references" section as the single bibliography and adopt "Author (Year), Eq. (N)" for all in-source citations. Confirm and correct four references (via literature search): - Hu (2018): NUDT PhD dissertation (Eq. 5.71 in the IITM recurrence) - Bi et al. (2014) -> Bi & Yang (2014), JQSRT 138 (two authors) - Sh-matrix: Farafonov et al. (2003) origin; Petrov et al. (2007) coined the name - Xu & Davis (2011): correct title + Opt. Lett. 36(22):4464
Convert inline math in docstrings from single-backtick code spans to Documenter inline LaTeX (double backticks) so formulas typeset in the rendered docs. Conservative scope: only multi-symbol expressions/relations are converted; parameter names, types, functions, and kwargs stay as code. Display ```math blocks unchanged; docstrings gaining backslashes switched to @doc raw.
📝 WalkthroughWalkthroughThis PR performs a comprehensive documentation expansion and release update: versioning the package to v0.5.0 (June 2026), restructuring the README and documentation site with new theory/references pages, enriching usage guidance and API organization, and standardizing citation formatting and docstring presentation across source code with no logic changes. ChangesDocumentation expansion and restructuring
Source code docstring standardization
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/src/usage.md`:
- Around line 41-43: The doc text incorrectly calls N a "type parameter" while
the example uses it as a constructor argument; update the wording to say that N
is the number of base edges and is supplied as the first argument to the Prism
constructor (e.g., Prism(6, ...)), clarifying that it is a runtime/constructor
parameter rather than a type parameter and adjust the sentence that mentions
"type parameter" accordingly (reference: Prism and the symbol N).
- Line 95: The current markdown mixes link and code formatting for the
recommendation string causing rendering issues; update the table cell so the
entire recommendation is treated as code inside the link—for example wrap the
whole label in backticks and then link it like [`Iterative(EBCM; stable =
true)`](`@ref`) so the symbols Iterative and the qualifier (EBCM; stable = true)
render correctly as inline code while remaining a link (target the table cell
containing "Iterative" and "(EBCM; stable = true)").
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 3b319ec2-9315-4677-b9ce-365f06912c70
📒 Files selected for processing (25)
CITATION.bibREADME.mddocs/make.jldocs/src/api.mddocs/src/examples/index.mddocs/src/index.mddocs/src/linearization.mddocs/src/performance.mddocs/src/references.mddocs/src/theory.mddocs/src/usage.mdsrc/EBCM/axisymmetric.jlsrc/EBCM/shmatrix.jlsrc/EBCM/stabilization.jlsrc/IITM/arbitrary.jlsrc/IITM/axisymmetric.jlsrc/IITM/nfold.jlsrc/Mie/MieTransitionMatrix.jlsrc/Mie/bhcoat.jlsrc/Mie/bhmie.jlsrc/common/AbstractTransitionMatrix.jlsrc/common/AxisymmetricTransitionMatrix.jlsrc/common/RandomOrientationTransitionMatrix.jlsrc/solvers.jlsrc/special_functions/wignerd.jl
Comment on lines
+41
to
+43
| The following defines a hexagonal prism (`N = 6` base edges) with base edge | ||
| length `a = 1.0`, height `h = 2.0`, and refractive index `m = 1.5 + 0.01im`. The | ||
| number of base edges is a type parameter, supplied as the first argument: |
There was a problem hiding this comment.
Clarify Prism parameter wording (type parameter vs argument).
This text says N is a type parameter, but the example passes it as a normal constructor argument (Prism(6, ...)). Please reword to avoid API confusion.
Proposed doc fix
-The number of base edges is a type parameter, supplied as the first argument:
+The number of base edges is supplied as the first constructor argument:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| The following defines a hexagonal prism (`N = 6` base edges) with base edge | |
| length `a = 1.0`, height `h = 2.0`, and refractive index `m = 1.5 + 0.01im`. The | |
| number of base edges is a type parameter, supplied as the first argument: | |
| The following defines a hexagonal prism (`N = 6` base edges) with base edge | |
| length `a = 1.0`, height `h = 2.0`, and refractive index `m = 1.5 + 0.01im`. The | |
| number of base edges is supplied as the first constructor argument: |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/src/usage.md` around lines 41 - 43, The doc text incorrectly calls N a
"type parameter" while the example uses it as a constructor argument; update the
wording to say that N is the number of base edges and is supplied as the first
argument to the Prism constructor (e.g., Prism(6, ...)), clarifying that it is a
runtime/constructor parameter rather than a type parameter and adjust the
sentence that mentions "type parameter" accordingly (reference: Prism and the
symbol N).
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #10 +/- ##
=======================================
Coverage 95.63% 95.63%
=======================================
Files 32 32
Lines 4403 4403
=======================================
Hits 4211 4211
Misses 192 192
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Home gains installation/quick-start/navigation/how-to-cite; new Theory & conventions, Examples overview, Performance, and References pages; API reorganized into categorized sections; Usage adds Prism, a solver-selection guide, and runnable post-processing/orientation-averaging examples; Linearization gains a support table and EBCM example. Document the AxisymmetricTransitionMatrix type and bump CITATION.bib to v0.5.0. All runnable examples verified to execute; site builds clean.
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/src/theory.md (1)
77-84: ⚡ Quick winConsider clarifying the orientation distribution convention.
The
orientation_averagefunction documentation explicitly notes that "thesin(β)part is already included" in the integration measure, meaning users should providepₒ(α, β, γ)without thesin(β)factor. Adding this convention to the theory page would help users correctly write custom orientation distributions.📝 Suggested clarification
Consider adding after line 81:
integrates numerically against a user-supplied orientation distribution and -converges to the analytic result. The orientation-averaged **scattering matrix** +converges to the analytic result. (Note: when passing a custom distribution `pₒ` +to `orientation_average`, the `sin(β)` Jacobian factor is already included in +the integration measure.) The orientation-averaged **scattering matrix** is expanded in generalised spherical functions with coefficients computed by [`expansion_coefficients`](`@ref`).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/src/theory.md` around lines 77 - 84, Add a short clarification to the theory text explaining the orientation-distribution convention used by orientation_average: state that orientation_average expects the user-supplied distribution pₒ(α, β, γ) WITHOUT the sin(β) factor because the integration measure already includes sin(β), and mention that this contrasts with the analytic RandomOrientationTransitionMatrix result (and that expansion_coefficients uses the same convention), so users should omit sin(β) when writing custom distributions.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/src/theory.md`:
- Around line 77-84: Add a short clarification to the theory text explaining the
orientation-distribution convention used by orientation_average: state that
orientation_average expects the user-supplied distribution pₒ(α, β, γ) WITHOUT
the sin(β) factor because the integration measure already includes sin(β), and
mention that this contrasts with the analytic RandomOrientationTransitionMatrix
result (and that expansion_coefficients uses the same convention), so users
should omit sin(β) when writing custom distributions.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: fa085dfd-b1c7-4526-8021-5a8916679e38
📒 Files selected for processing (12)
CITATION.bibREADME.mddocs/make.jldocs/src/api.mddocs/src/examples/index.mddocs/src/index.mddocs/src/linearization.mddocs/src/performance.mddocs/src/references.mddocs/src/theory.mddocs/src/usage.mdsrc/common/AxisymmetricTransitionMatrix.jl
✅ Files skipped from review due to trivial changes (9)
- docs/src/examples/index.md
- CITATION.bib
- docs/src/references.md
- docs/src/api.md
- README.md
- src/common/AxisymmetricTransitionMatrix.jl
- docs/src/linearization.md
- docs/src/performance.md
- docs/src/index.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/make.jl
- docs/src/usage.md
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
1 participant
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.
Summary by CodeRabbit
Documentation
Chores