Revising the addition of a docstring

[mbauman]

Ok, this is a little silly, but I was just demoing Revise to someone and blindly tried adding a docstring, expecting it to become available (akin to other changes).

Not a crucial thing, but could be nice to support.

[timholy]

Should work? 200 lines of tests say so!

Revise.jl/test/runtests.jl

Lines 1055 to 1269 in 1dd0a70

	do_test("Module docstring") && @testset "Module docstring" begin
	testdir = newtestdir()
	dn = joinpath(testdir, "ModDocstring", "src")
	mkpath(dn)
	open(joinpath(dn, "ModDocstring.jl"), "w") do io
	println(io, """
	" Ahoy! "
	module ModDocstring
	include("dependency.jl")
	f() = 1
	end
	""")
	end
	open(joinpath(dn, "dependency.jl"), "w") do io
	println(io, "")
	end
	sleep(mtimedelay)
	@eval using ModDocstring
	sleep(mtimedelay)
	@test ModDocstring.f() == 1
	ds = @doc(ModDocstring)
	@test get_docstring(ds) == "Ahoy! "
	open(joinpath(dn, "ModDocstring.jl"), "w") do io
	println(io, """
	" Ahoy! "
	module ModDocstring
	include("dependency.jl")
	f() = 2
	end
	""")
	end
	yry()
	@test ModDocstring.f() == 2
	ds = @doc(ModDocstring)
	@test get_docstring(ds) == "Ahoy! "
	open(joinpath(dn, "ModDocstring.jl"), "w") do io
	println(io, """
	" Hello! "
	module ModDocstring
	include("dependency.jl")
	f() = 3
	end
	""")
	end
	yry()
	@test ModDocstring.f() == 3
	ds = @doc(ModDocstring)
	@test get_docstring(ds) == "Hello! "
	rm_precompile("ModDocstring")
	# issue #197
	dn = joinpath(testdir, "ModDocstring2", "src")
	mkpath(dn)
	open(joinpath(dn, "ModDocstring2.jl"), "w") do io
	println(io, """
	"docstring"
	module ModDocstring2
	"docstring for .Sub"
	module Sub
	end
	end
	""")
	end
	sleep(mtimedelay)
	@eval using ModDocstring2
	sleep(mtimedelay)
	ds = @doc(ModDocstring2)
	@test get_docstring(ds) == "docstring"
	ds = @doc(ModDocstring2.Sub)
	@test get_docstring(ds) == "docstring for .Sub"
	open(joinpath(dn, "ModDocstring2.jl"), "w") do io
	println(io, """
	"updated docstring"
	module ModDocstring2
	"updated docstring for .Sub"
	module Sub
	end
	end
	""")
	end
	yry()
	ds = @doc(ModDocstring2)
	@test get_docstring(ds) == "updated docstring"
	ds = @doc(ModDocstring2.Sub)
	@test get_docstring(ds) == "updated docstring for .Sub"
	rm_precompile("ModDocstring2")
	pop!(LOAD_PATH)
	end
	do_test("Changing docstrings") && @testset "Changing docstring" begin
	# Compiled mode covers most docstring changes, so we have to go to
	# special effort to test the older interpreter-based solution.
	testdir = newtestdir()
	dn = joinpath(testdir, "ChangeDocstring", "src")
	mkpath(dn)
	open(joinpath(dn, "ChangeDocstring.jl"), "w") do io
	println(io, """
	module ChangeDocstring
	"f" f() = 1
	end
	""")
	end
	sleep(mtimedelay)
	@eval using ChangeDocstring
	sleep(mtimedelay)
	@test ChangeDocstring.f() == 1
	ds = @doc(ChangeDocstring.f)
	@test get_docstring(ds) == "f"
	# Ordinary route
	open(joinpath(dn, "ChangeDocstring.jl"), "w") do io
	println(io, """
	module ChangeDocstring
	"h" f() = 1
	end
	""")
	end
	yry()
	ds = @doc(ChangeDocstring.f)
	@test get_docstring(ds) == "h"
	# Now manually change the docstring
	ex = quote "g" f() = 1 end
	lwr = Meta.lower(ChangeDocstring, ex)
	frame = Frame(ChangeDocstring, lwr.args[1])
	methodinfo = Revise.MethodInfo()
	docexprs = Revise.DocExprs()
	ret = Revise.methods_by_execution!(JuliaInterpreter.finish_and_return!, methodinfo,
	docexprs, frame, trues(length(frame.framecode.src.code)); mode=:sigs)
	ds = @doc(ChangeDocstring.f)
	@test get_docstring(ds) == "g"
	rm_precompile("ChangeDocstring")
	pop!(LOAD_PATH)
	end
	do_test("Undef in docstrings") && @testset "Undef in docstrings" begin
	fn = Base.find_source_file("abstractset.jl") # has lots of examples of """str""" func1, func2
	mexsold = Revise.parse_source(fn, Base)
	mexsnew = Revise.parse_source(fn, Base)
	odict = mexsold[Base]
	ndict = mexsnew[Base]
	for (k, v) in odict
	@test haskey(ndict, k)
	end
	end
	do_test("Macro docstrings (issue #309)") && @testset "Macro docstrings (issue #309)" begin
	testdir = newtestdir()
	dn = joinpath(testdir, "MacDocstring", "src")
	mkpath(dn)
	open(joinpath(dn, "MacDocstring.jl"), "w") do io
	println(io, """
	module MacDocstring
	macro myconst(name, val)
	quote
	\"\"\"
	mydoc
	\"\"\"
	const \$(esc(name)) = \$val
	end
	end
	@myconst c 1.2
	f() = 1
	end # module
	""")
	end
	sleep(mtimedelay)
	@eval using MacDocstring
	sleep(mtimedelay)
	@test MacDocstring.f() == 1
	ds = @doc(MacDocstring.c)
	@test strip(get_docstring(ds)) == "mydoc"
	open(joinpath(dn, "MacDocstring.jl"), "w") do io
	println(io, """
	module MacDocstring
	macro myconst(name, val)
	quote
	\"\"\"
	mydoc
	\"\"\"
	const \$(esc(name)) = \$val
	end
	end
	@myconst c 1.2
	f() = 2
	end # module
	""")
	end
	yry()
	@test MacDocstring.f() == 2
	ds = @doc(MacDocstring.c)
	@test strip(get_docstring(ds)) == "mydoc"
	rm_precompile("MacDocstring")
	pop!(LOAD_PATH)
	end

Which of course just means that there is some other error or circumstances that are missing tests.

[mbauman]

Interesting. Here's what I was trying (Julia 1.5.0, Revise 3.1.9)

module TestPackage

greet(name="World") = "Hello $(name), nice to meet you!"

end # module

julia> using Revise

julia> using TestPackage
[ Info: Precompiling TestPackage [606d46c6-36d6-41d4-9f3b-24d4fb92e632]

julia> TestPackage.greet("me")
"Hello me, nice to meet you!"

help?> TestPackage.greet
  No documentation found.

Edit the module to contain:

module TestPackage

"""
    greet

foo
"""
greet(name="World") = "Hello to $(name), so glad to see you!"

end # module

then:

julia> TestPackage.greet("Grandma Yvette")
"Hello to Grandma Yvette, so glad to see you!"

help?> TestPackage.greet
  No documentation found.

[mbauman]

Ah, it works if it already has a docstring — it's the adding of a new docstring that doesn't.

[timholy]

Color me amazed. Despite trying to set up good APIs and sensible logic, I get caught over and over again by subtle differences blocking something that should work. It seems that almost every single thing anyone ever wants to do needs a test.

[mbauman]

I just need to do more live and interactive demos. They have a way of exploring new paths in fun and exciting ways!

[timholy]

You are so right. I notice everything bad about Julia whenever I'm teaching someone new or demonstrating how awesome it is. 😆

[timholy]

It also requires that the module have no docstrings whatsoever. It's a Julia bug. Fix coming momentarily.

[timholy]

xref JuliaLang/julia#38819 and fix in 38821.