JOSS Review - Remarks About Docs

May 3, 2025 by ADMIN 33 views

**JOSS Review: Remarks on Documentation**

As part of the JOSS review of your paper, I have compiled some remarks on the stable documentation. These comments aim to provide constructive feedback to improve the overall quality and clarity of the documentation.

General Documentation

Separation of Public and Private API

Please ensure that all examples included in the documentation are included as doctests.
It seems that every single object is documented and placed on the corresponding page. To improve the documentation, there needs to be a clearer separation between public and private API. By default, in Julia, what is documented is public unless stated otherwise. Starting with Julia 1.11, the public keyword enables a clearer distinction.

Public and Private API

In Julia, the public keyword is used to indicate that a function or type is part of the public API. This is particularly important when documenting code, as it helps users understand what is intended to be used and what is not. By default, Julia documents everything, but using the public keyword can help to clarify the API and make it easier for users to understand.

Doctests

Doctests are a great way to include examples in the documentation. They allow users to run the examples directly from the documentation, which can be very helpful for understanding how to use the code. To include doctests, simply use the @doctest macro at the top of the documentation block.

Example

Here is an example of how to include a doctest:

"""
    my_function(x)

This is a description of the function.

# Examples
```jldoctest
julia> my_function(1)
2

""" function my_function(x) return x + 1 end


### Public and Private API

To separate the public and private API, you can use the `public` keyword to indicate which functions and types are part of the public API. For example:

```julia
"""
    public function my_public_function(x)

This is a description of the public function.

# Examples
```jldoctest
julia> my_public_function(1)
2

""" public function my_public_function(x) return x + 1 end

""" private function my_private_function(x)

This is a description of the private function.

julia> my_private_function(1)
2

""" function my_private_function(x) return x + 1 end


### Math Display

To display math properly, you can use the backtick syntax (instead of dollar signs) to avoid alignment issues. For example:

```julia
"""
    my_function(x)

This is a description of the function.

# Examples
```jldoctest
julia> my_function(1)
2

""" function my_function(x) return x + 1 end


### Matrices of Size 0

It might be helpful to explain why it makes sense to construct the default `GaussianStateModel` with matrices of size 0.

**Home Page**
------------

### Example

*   The first example on the home page fails with SSD v0.1.1 and the latest Julia 1.11.

```julia
julia> x, y = sample(lds, 1000)  # 1000 timepoints
ERROR: MethodError: no method matching sample(::StateSpaceDynamics.LinearDynamicalSystem{…}, ::Int64)
The function `sample` exists, but no method is defined for this combination of argument types.

Closest candidates are:
  sample(::StateSpaceDynamics.LinearDynamicalSystem{S, O}, ::Int64, ::Int64) where {T<:Real, S<:StateSpaceDynamics.GaussianStateModel{T}, O<:StateSpaceDynamics.GaussianObservationModel{T}}
   @ StateSpaceDynamics ~/.julia/packages/StateSpaceDynamics/zrsML/src/LinearDynamicalSystems.jl:299
  sample(::SwitchingLinearDynamicalSystem, ::Int64)
   @ StateSpaceDynamics ~/.julia/packages/StateSpaceDynamics/zrsML/src/SLDS.jl:16
  sample(::GaussianMixtureModel, ::Int64)
   @ StateSpaceDynamics ~/.julia/packages/StateSpaceDynamics/zrsML/src/MixtureModels.jl:46
  ...

Stacktrace:
 [1] top-level scope
   @ ~/Documents/GitHub/Julia/_Scratchpad/mwe.jl:10
Some type information was truncated. Use `show(err)` to see complete types.

Link to Repo

The link to the repo is outdated.

Contribution Guidelines

Contribution guidelines should be expanded a little.

Citation

For citation, you could add a Zenodo DOI.

Models

Docstrings

It might help to intersperse the docstrings with the text? You can force them to be collapsed by default to avoid taking too much space.

Math Display

The math doesn't display properly. For the list you might need the backtick syntax (instead of dollar signs) to avoid these alignment issues.

Matrices of Size 0

Why does it make sense to construct the default GaussianStateModel with matrices of size 0?

Q: What is the purpose of doctests in documentation?

A: Doctests are a great way to include examples in the documentation. They allow users to run the examples directly from the documentation, which can be very helpful for understanding how to use the code.

Q: How do I include doctests in my documentation?

A: To include doctests, simply use the @doctest macro at the top of the documentation block. Here is an example:

"""
    my_function(x)

This is a description of the function.

# Examples
```jldoctest
julia> my_function(1)
2

""" function my_function(x) return x + 1 end


**Q: What is the difference between public and private API?**
---------------------------------------------------------

A: In Julia, the `public` keyword is used to indicate that a function or type is part of the public API. This is particularly important when documenting code, as it helps users understand what is intended to be used and what is not. By default, Julia documents everything, but using the `public` keyword can help to clarify the API and make it easier for users to understand.

**Q: How do I separate the public and private API in my documentation?**
-------------------------------------------------------------------

A: To separate the public and private API, you can use the `public` keyword to indicate which functions and types are part of the public API. For example:

```julia
"""
    public function my_public_function(x)

This is a description of the public function.

# Examples
```jldoctest
julia> my_public_function(1)
2

""" public function my_public_function(x) return x + 1 end

""" private function my_private_function(x)

This is a description of the private function.

julia> my_private_function(1)
2

""" function my_private_function(x) return x + 1 end


**Q: Why does the math not display properly in my documentation?**
----------------------------------------------------------------

A: To display math properly, you can use the backtick syntax (instead of dollar signs) to avoid alignment issues. For example:

```julia
"""
    my_function(x)

This is a description of the function.

# Examples
```jldoctest
julia> my_function(1)
2

""" function my_function(x) return x + 1 end


**Q: What is the purpose of the `public` keyword in Julia?**
---------------------------------------------------------

A: The `public` keyword is used to indicate that a function or type is part of the public API. This is particularly important when documenting code, as it helps users understand what is intended to be used and what is not.

**Q: How do I add Zenodo DOI to my citation?**
------------------------------------------------

A: To add a Zenodo DOI to your citation, you can simply include the DOI in the citation. For example:

```julia
"""
    my_paper

This is a description of the paper.

# Citation
@article{my_paper,
    title = {My Paper},
    author = {Author},
    year = {2022},
    doi = {10.1234/56789},
}
"""

Q: What is the purpose of the `@doctest` macro?

A: The @doctest macro is used to include examples in the documentation. It allows users to run the examples directly from the documentation, which can be very helpful for understanding how to use the code.

Q: How do I fix the failing example on the home page?

A: To fix the failing example on the home page, you will need to update the code to match the latest version of the package. You can do this by checking the package's documentation and updating the code accordingly.

Q: What is the purpose of the `public` keyword in the `GaussianStateModel` constructor?

A: The public keyword is used to indicate that the GaussianStateModel constructor is part of the public API. This is particularly important when documenting code, as it helps users understand what is intended to be used and what is not.

Q: How do I add a link to the repo in my documentation?

A: To add a link to the repo in your documentation, you can simply include the link in the documentation. For example:

"""
    my_paper

This is a description of the paper.

# Links
*   [Repo](https://github.com/username/repo)
"""

Q: What is the purpose of the `contribution` section in the documentation?

A: The contribution section in the documentation is used to provide information on how to contribute to the package. This can include information on how to submit issues, pull requests, and how to contribute code.

Q: How do I add a Zenodo DOI to my citation?

A: To add a Zenodo DOI to your citation, you can simply include the DOI in the citation. For example:

"""
    my_paper

This is a description of the paper.

# Citation
@article{my_paper,
    title = {My Paper},
    author = {Author},
    year = {2022},
    doi = {10.1234/56789},
}
"""

In conclusion, I hope this Q&A article has provided helpful information on how to improve the documentation of your package. If you have any further questions or concerns, please do not hesitate to reach out.

How Do I Remove This Cabinet Drawer?

May 3, 2025 36 views

Exercise: Introduction To GitHub

May 3, 2025 32 views

General Documentation

Separation of Public and Private API

Public and Private API

Doctests

Example

Link to Repo

Contribution Guidelines

Citation

Models

Docstrings

Math Display

Matrices of Size 0

Q: What is the purpose of doctests in documentation?

Q: How do I include doctests in my documentation?

Q: What is the purpose of the @doctest macro?

Q: How do I fix the failing example on the home page?

Q: What is the purpose of the public keyword in the GaussianStateModel constructor?

Q: How do I add a link to the repo in my documentation?

Q: What is the purpose of the contribution section in the documentation?

Q: How do I add a Zenodo DOI to my citation?

Q: What is the purpose of the `@doctest` macro?

Q: What is the purpose of the `public` keyword in the `GaussianStateModel` constructor?

Q: What is the purpose of the `contribution` section in the documentation?