[DOC] Statement of the APIs about agents.jl HOT 9 CLOSED

Hi,
Thanks for the suggestions. I was on vacation. I will try to address your comments as soon as possible.

from agents.jl.

Cool, thanks, I'll have a look soon!

from agents.jl.

Hm, the more I read the Schelling's model tutorial, the more I see that what I ask for is already existing. This could be solved with minimal effort, by making Schelling's tutorial a first-level page by itself (instead of being grouped in the examples) and changing titles and making everything a bit more visible.

Some other title is necessary, so that it is obvious from a glance that this page does serve as an "introduction" to Agents.jl. I suggest to make the First level title Agent's.jl Architecture and add a second title later on Schelling's segregation model Example.

(what I said above, to state the expected API independently of an example, is still very useful)

from agents.jl.

The Table of Contents also starts with the forest fire model. Some re-organization there could help as well, so that it starts with basic API introduction instead.

from agents.jl.

The docs are now refactored as you suggested.

from agents.jl.

I am reading the new documentation currently. I have some comments that might sound nit-picky but I think can really help improve the docs. Recall that I am in no way a user already familiar with Agents.jl and thus my comments (I believe) do give you the impression of what a newcomer would think.

Anyway, here goes: I think the "Defining a space object" from the documentation is unecessary. I think the functionality that a user can define their own grid is cool, but way too advanced for an introductory tutorial. Maybe a different tutorial on "making your own space" is in order, and instead in the introductory tutorial you can use the function grid, and reference it using the syntax [`grid`](@ref).

I stand that understanding LightGraphs.jl should not be necessary to use the basics of Agents.jl, but in order to create a "Space" by yourself, you really have to know LightGraphs.jl. In fact, I don't at all understand why one has to create a space by themselves.

EDIT: What I say in this section is largely tied with, and in part superseded by #24

The usage of terms "grid" and "space" is confusing, because they don't really have a proper definition. Do they mean the same thing? (for someone with my background, condensed matter, they could) What does "grid" mean? The documentation of grid states:

Return a grid based on its dimensions...

but does not state what a grid actually is. By running the function I realize it is a SimpleGraph. This should be stated in the documentation string explicitly. Users not already familiar with Agents.jl will have to guess what grid means.

from agents.jl.

Thank you.
Indeed, understanding LightGraphs.jl is not necessary for using Agents.jl. For any regular space, the user only needs to provide dimensions of the space. This is what happens in all of the examples. So there is no direct interaction with LightGraphs.jl.

I have mentioned that it is possible for users to create and input a custom irregular space for their simulations. This is a useful option as not all simulations happen in a regular grid.

I can add a description to docstrings defining a grid.

from agents.jl.

@kavir1698 I'll close this (and thus fullfill the point in the JOSS review) once you simply state in the docstrings of grid that they return a SimpleGraph. Nothing more is currently necessary and implementing #24 is not necessary for the review.

from agents.jl.

Cool, kavir1698@9b16776 addresses your comment.

from agents.jl.