# ANN: Announcing DoctorDocstrings.jl

**URL:** <https://discourse.julialang.org/t/ann-announcing-doctordocstrings-jl/51999>\
**Category:** Package Announcements\
**Tags:** package, announcement, documentation\
**Created:** [December 17, 2020, 5:20pm UTC](https://discourse.julialang.org/t/ann-announcing-doctordocstrings-jl/51999 "2020-12-17T17:20:55Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![miguelraz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/miguelraz/32/631_2.png) [@miguelraz](https://discourse.julialang.org/u/miguelraz)\
**Post date:** [December 17, 2020, 5:20pm UTC](https://discourse.julialang.org/t/ann-announcing-doctordocstrings-jl/51999/1 "2020-12-17T17:20:55Z")

</div>

Hello all!

[DoctorDocstrings.jl](https://github.com/miguelraz/DoctorDocstrings.jl) is a package that will help you enhance your REPL workflow for adding docstrings to your package. It is very simple, alpha, and hardcoded (for now). ~~Dear lord don’t judge me from the janky hacks it’s awful awful~~. But it works! [The docs are here.](https://miguelraz.github.io/DoctorDocstrings.jl/)

The idea is to

1. `listdocs($MyPackage)` to know see all exports in your package/module and `true/false` for having docstrings/examples.
2. `diagnosedocs($MyPackage)` if you only want to know the ones that are missing docstrings
3. Now that you know which one you want to add docstrings to, you play around with some inputs in the REPL.
4. `fixdocs()` select from your REPL history which inputs you want, choose a docstrings template, and step in to `@edit` the last selected input. The previous REPL entries are in your clipboard, so just pasting should work.

Here’s a live 3 minute demo to show the workflow.

[![](https://global.discourse-cdn.com/julialang/original/3X/0/e/0eb20a6482e0753aec3bd7f6ec7e29c364438916.jpeg "Live tutorial - DoctorDocstrings.jl!") ](https://www.youtube.com/watch?v=gmEqa6SOVog)

Comments, issues, PRs welcome.

### Acknowledgments

Thanks a lot to @mbauman for early feedback, @PetrKryslUCSD for REPLHistory.jl, (a good reference for this project), and @StefanKarpinski for “incepting” this idea into my todo-list, and @tlienart for help with the documentation.

---

<div class="post-metadata">

**Author:** ![Datseris](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/datseris/32/13406_2.png) [@Datseris](https://discourse.julialang.org/u/Datseris)\
**Post date:** [December 17, 2020, 5:29pm UTC](https://discourse.julialang.org/t/ann-announcing-doctordocstrings-jl/51999/2 "2020-12-17T17:29:45Z")

</div>

Beautiful, and pure gold for the name.

It’s not so clear from the docs what quantifies as an “example”. Care to provided a (very explicit, very specific) definition?

To be clear: how does the package decides if one of my docstrings has, or has not, an example? I don’t mean “how do you write examples”

---

<div class="post-metadata">

**Author:** ![miguelraz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/miguelraz/32/631_2.png) [@miguelraz](https://discourse.julialang.org/u/miguelraz)\
**Post date:** [December 17, 2020, 5:33pm UTC](https://discourse.julialang.org/t/ann-announcing-doctordocstrings-jl/51999/3 "2020-12-17T17:33:28Z")

</div>

Thanks, I just added the link.

Here’s what I mean by examples - anything that is copy/pasteable Julia code that comes after `Examples\n====` in the docstring, like what is in `?parse`:

```julia
  Examples
  ≡≡≡≡≡≡≡≡≡≡

  julia> parse(Int, "1234")
  1234

  julia> parse(Int, "1234", base = 5)
  194

  julia> parse(Int, "afc", base = 16)
  2812

  julia> parse(Float64, "1.2e-3")
  0.0012

```

The logic for checking if it has examples is very unsophisticated - I just splat everything onto a string and check for the existence of a `Examples\n====` occurring. I’m open to suggestions on how not to jankily abuse the doc internals 😅. (This works for enough use cases as a hack that perfect is the enemy of the good for shipping, so I thought I’d nerdsnipe someone into helping me implement something better .)

---

<div class="post-metadata">

**Author:** ![dmolina](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/dmolina/32/5246_2.png) [@dmolina](https://discourse.julialang.org/u/dmolina)\
**Post date:** [December 17, 2020, 5:34pm UTC](https://discourse.julialang.org/t/ann-announcing-doctordocstrings-jl/51999/4 "2020-12-17T17:34:34Z")

</div>

Sometimes you do not realise how much you want/need a package doing something until you see a package and see how great idea is it. It is a great idea. I will try with my code and then I will give my feedback.

---

<div class="post-metadata">

**Author:** ![Datseris](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/datseris/32/13406_2.png) [@Datseris](https://discourse.julialang.org/u/Datseris)\
**Post date:** [December 17, 2020, 5:35pm UTC](https://discourse.julialang.org/t/ann-announcing-doctordocstrings-jl/51999/5 "2020-12-17T17:35:26Z")

</div>

Great, `Examples\n====` is exactly what I was looking for. Would be good to extend this with other possibilities. So far I have always used `## Example` or `## Examples`, so It would be good to provide a keyword like `example_quantifier = ["Examples\n====", "## Examples"...]` that has _a lot_ of defaults

---

<div class="post-metadata">

**Author:** ![miguelraz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/miguelraz/32/631_2.png) [@miguelraz](https://discourse.julialang.org/u/miguelraz)\
**Post date:** [December 17, 2020, 5:39pm UTC](https://discourse.julialang.org/t/ann-announcing-doctordocstrings-jl/51999/6 "2020-12-17T17:39:01Z")

</div>

Thanks! I do hope other people like the REPL mucking about + `fixdocs()` workflow.

---

<div class="post-metadata">

**Author:** ![miguelraz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/miguelraz/32/631_2.png) [@miguelraz](https://discourse.julialang.org/u/miguelraz)\
**Post date:** [December 17, 2020, 5:39pm UTC](https://discourse.julialang.org/t/ann-announcing-doctordocstrings-jl/51999/7 "2020-12-17T17:39:54Z")

</div>

Sounds like an excellent PR to handle edge cases 😃

---

<div class="post-metadata">

**Author:** ![miguelraz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/miguelraz/32/631_2.png) [@miguelraz](https://discourse.julialang.org/u/miguelraz)\
**Post date:** [December 18, 2020, 1:32am UTC](https://discourse.julialang.org/t/ann-announcing-doctordocstrings-jl/51999/8 "2020-12-18T01:32:50Z")

</div>

Just found a bug that has to do with (I think) macro hygiene.

If I input

```julia
julia> using SparseArrays

julia> A = sparsevec([1,2,3], [1.0, 0.0, 1.0])
3-element SparseVector{Float64, Int64} with 3 stored entries:
  [1] = 1.0
  [2] = 0.0
  [3] = 1.0

julia> dropzeros!(A)
3-element SparseVector{Float64, Int64} with 2 stored entries:
  [1] = 1.0
  [3] = 1.0

```

And I select them with `pickandcopy()`, which tries to `@eval Meta.parse(inputstring)`, I get `sparsevec not defined`.

Any help?