JuliaDynamics/DrWatson.jl

The examples in the document are inconsistent with the API interface

Open

#410 opened on Apr 9, 2024

View on GitHub
 (1 comment) (0 reactions) (0 assignees)Julia (915 stars) (94 forks)batch import
documentationgood first issue

Description

I'm so grateful to the authors for this great package, it helped me tremendously! But when I was reading the documentation recently, I found that the calling order of parameters in the sample code of produce_or_load was inconsistent with the API description. Documentation at https://juliadynamics.github.io/DrWatson.jl/stable/real_world/#Stopping-%22Did-I-run-this?%22. The example is given by

N = 2000; T = 2000.0
data, file = produce_or_load(
    datadir("mushrooms", "toy"), # path
    @dict(N, T), # container
    simulation; # function
    prefix = "fig5_toyparams" # prefix for savename
)
@unpack toypar_h = data

However, the definition of produce_or_load is given by

produce_or_load(f::Function, config, path = ""; kwargs...) -> data, file

Their parameter order is reversed, will this work fine either way?

Contributor guide

Tech stack
None
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
under 1 hour
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
needs maintainer response
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
needs investigation
Prerequisites
basic DrWatson package usage
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
First, verify the correct parameter order for produce or load by examining its source code in the DrWatson.jl repository (likely in src/). The current documentation example shows the order (path, config, function) while the API signature shows (function, config, path). Confirm which order is intended and update either the example in the documentation file (e.g., docs/src/real world.md) or the API documentation accordingly. If the example is correct, the function signature comment in the source code may need correction.