-
Notifications
You must be signed in to change notification settings - Fork 116
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add docstring support to @agent #715
Comments
To add a docstring you'd do: @agent MyAgent .....
....
end
@doc "lalalala"
MyAgent But yes, it would be nice to have a clearer example in the docstring, please consider a PR! I don't know how we could modify |
I've now used macro agent(new_name, base_type, extra_fields)
quote
let
# Here we collect the field names and types from the base type
# Because the base type already exists, we escape the symbols to obtain it
base_fieldnames = fieldnames($(esc(base_type)))
base_fieldtypes = [t for t in getproperty($(esc(base_type)), :types)]
base_fields = [:($f::$T) for (f, T) in zip(base_fieldnames, base_fieldtypes)]
# Then, we prime the additional name and fields into QuoteNodes
# We have to do this to be able to interpolate them into an inner quote.
name = $(QuoteNode(new_name))
additional_fields = $(QuoteNode(extra_fields.args))
# Now we start an inner quote. This is because our macro needs to call `eval`
# However, this should never happen inside the main body of a macro
# There are several reasons for that, see the cited discussion at the top
expr = quote
Core.@__doc__ mutable struct $name <: AbstractAgent # <<< ADD @__doc__ HERE <<<
$(base_fields...)
$(additional_fields...)
end
end
# @show expr # uncomment this to see that the final expression looks as desired
# It is important to evaluate the macro in the module that it was called at
Core.eval($(__module__), expr)
end
end
end I haven't managed to get a development version of Agents.jl working yet to test this, but it should do it. |
What do you mean? Why not? It's great that you found a potential solution but I am out of bandwidth at the moment so a PR is much much appreciated! |
Sorry about that - I still don't fully understand Julia's package system and hadn't yet figured out how to get a local version of a package to run. But I've got everything set up now 👍
I'm working on it. Unfortunately, I discovered that the solution suggested above doesn't work due to the nested quoting. I'll see if I can figure out how to by-pass this issue. Otherwise, I'll just add a documentation note to |
Feel free to open a question at Discourse! |
I commented on this recent question: https://discourse.julialang.org/t/access-docstring-within-a-macro/90362 Let's see if anyone has any bright ideas. |
You'll need to do something like the following because of the use of diff --git a/src/core/agents.jl b/src/core/agents.jl
index e72e978..7771e13 100644
--- a/src/core/agents.jl
+++ b/src/core/agents.jl
@@ -197,6 +197,8 @@ macro agent(new_name, base_type, extra_fields)
# It is important to evaluate the macro in the module that it was called at
Core.eval($(__module__), expr)
end
+ Core.@__doc__($(esc(Docs.namify(new_name))))
+ nothing
end
end
# TODO: I do not know how to merge these two macros to remove code duplication.
@@ -234,6 +236,8 @@ macro agent(new_name, base_type, super_type, extra_fields)
# It is important to evaluate the macro in the module that it was called at
Core.eval($(__module__), expr)
end
+ Core.@__doc__($(esc(Docs.namify(new_name))))
+ nothing
end
end I've not thoroughly tested the above, so there might be some additional changes you'd need to do to make it work in every case that If you want to be able to do documentation of fields of the resulting |
Fixes issue JuliaDynamics#715. With thanks to Michael Hatherly!
Oh wonderful, thank you very much! I spent most of the day trying to fix this, didn't think it would turn out to be so easy... I hadn't thought of simply |
* Added docstring support to @agent Fixes issue #715. With thanks to Michael Hatherly! * Removed separate `@doc` calls with `@agent` `@agent` can now take a docstring directly, instead of relying on an additional call to `@doc`. * Removed superflous `Core.@__doc__` * Removed superfluous comment * Added test for docstring capture * Bumped patch number
Attaching a docstring to an
@agent
definition fails with an error: `'@agent' not documentable. See 'Base.@doc' docs for details.' This is unexpected and problematic, as documenting agent types is important.The @agent documentation states: "You can use the @doc macro from Julia to document the generated struct if you wish so." However, this statement (1) is easy to overlook, and (2) does not provide an example. (I did not get
@doc
to work in conjunction with@agent
, and could not find a working example.)My understanding is that docstring support can be added to a macro using
@__doc__
. Adding this to@agents
would allow modellers to better document their code.The text was updated successfully, but these errors were encountered: