Documentation improvements and clarifications

[scheidan]

First, thanks a lot for Infiltrator! It is extremely helpful and has a very intuitive interface. Only the documentation is not yet as user friendly as the package. Below you find some of my confusions that may help to clarify the documentation.

How to use Infiltrator to debug a package?

It seems there is quite a bit of tribal knowledge how to Infiltrato to debug a package without adding it as package dependency. Unfortunately, this is not documented here.

What I gathered from discord:

1. using Infiltrator (maybe in startup.jl)
2. using Revise (maybe in startup.jl)
3. activate you envorinment
4. using YourPackage
5. place breakpoints in package code with Main.@infiltrate

Is this the current best practice? Having this in the section "Example Usage" would be very helpful.

Clarification needed I

The section about @infiltrate contains this:

You can also use

if isdefined(Main, :Infiltrator)
  Main.infiltrate(@__MODULE__, Base.@locals, @__FILE__, @__LINE__)
end

to infiltrate package code without any post-hoc evaluation into the module (because the functional form does not require Infiltrator to be loaded at compiletime).

Unfortunately I have no idea:

• How and when I should use it (use the three lines instead of Main.@infiltrate?)
• If/how I can provide a condition
• What "without any post-hoc evaluation into the module (because the functional form does not require Infiltrator to be loaded at compiletime)" means :)

Clarification needed II

I'm a bit puzzled about Auto-loading Infiltrator.jl:

• Why/when should use this instead if using Infiltrator in my startup? Is it doing something extra?
• How exactly do I use it? Just replace @infiltrate with @autoinfiltrate?
• What does "module-level statements in package code" mean in layman's terms?

[pfitzseb]

I added a usage section to the docs which should hopefully clarify those questions.