Check if a function has a docstring

General Usage
1

How can I check programmatically if a function has a docstring?

2

Use the @doc macro or the doc function:

https://docs.julialang.org/en/v1/manual/documentation/#Advanced-Usage

3

How can I tell if a name has a docstring using your proposed technique? For example

using Markdown
julia> dump(@doc md"")
Markdown.MD
  content: Array{Any}((3,))
    1: Markdown.Paragraph
      content: Array{Any}((1,))
        1: String "No documentation found."
    2: Markdown.Paragraph
      content: Array{Any}((2,))
        1: Markdown.Code
          language: String ""
          code: String "Markdown.@md_str"
        2: String " is a macro."
    3: Markdown.Code
      language: String ""
4

You could look for "No documentation found." as the first paragraph, I guess, though that is a bit ugly.

To check whether there is documentation for a particular symbol in a particular module, this seems to work, but relies on undocumented internals of the Docs module:

julia> hasdoc(mod::Module, sym::Symbol) = haskey(Base.Docs.meta(mod), Base.Docs.Binding(mod, sym));

julia> hasdoc(Base, :sum)
true

julia> hasdoc(Base, :foo)
false

It would be nice to export some kind of documented functionality here, but first it would be helpful to have an example of a practical application that needs this, in order to determine the appropriate functionality.

For example, it might be useful for Base.Test to provide a way to check that all exported symbols in a module have docstrings.

6 Likes
5

Yeah that’s what I’m going for. Though I think it’s even better practice to give all functions docstrings to help contributors.

6

I think this would be a very significant change to help R developers who are used to a dynamic language, but expecting the ‘check’ process of cran where packages have complete documentation on exported functions.

7

I filed an issue with an example implementation: add a way to test whether exported symbols are documented · Issue #51174 · JuliaLang/julia · GitHub

Anyone want to take a crack at it?

2 Likes
8

Do you mean make a pull request addressing the issue? (I don’t have time for that, but I hope that someone does)

If you just meant test your code, I did the following which works in 1.9 & 1.10:

using Test

@testset "hasdoc" begin
    @eval module Aa
        export good, bad

        """
        Better to do nothing than to do something bad
        """
        good() = nothing

        bad() = Inf
    end

    @test hasdoc(Aa, :good)
    @test hasdoc(Aa, :bad) == false
end
1 Like
9

Yes, I mean making a PR. This involves adding tests, documentation, going through the review process, etcetera.

1 Like