Expanded documentation on customization

[wlandau]

Even with this section in the vignette, I find it difficult to learn how to customize CodeDepends and to understand how it does what it does. If you could break down the terminology, concepts, and mechanics, and if you could provide a lengthier suite of examples, I think it would really help.

In fact, I think the entire field of static code analysis in R lacks thorough and accessible documentation. The most useful guidance I have found is here. Still looking for a proper entry point into the space.

[gmbecker]

That is understandable. Writing this kind of stuff is hard, and I had hoped that the default function handlers themselves would be somewhat self-documenting, but looking at them I can see that's only the case for someone already pretty well-steeped in low-level computation on parsed expressions.

I don't have the cycles to do this now, but I'm going to have to wade back into this stuff to handle all the !! stuff coming out of rlang anyway (that isn't going to be fun) and I'll work to add better docs then if not before.

In the meantime shoot me an email if uyou ahve any specific questions on how something would be done, and anything we come up with we can add to the vignette or docs for posterity.

[wlandau]

Thanks, Gabe! I would be happy to help with this going forward, time and knowledge permitting.

[gmbecker]

For the record, and I know this isn't particularly helpful or how it should be, but I learned this stuff via a combination of reading the source code of the previous versions of CodeDepends, and by manually constructing expressions and inspecting them via double-bracketing into them:

> expr = parse(text = "f(x, y, f2(z, rnorm(5)))")
> expr
expression(f(x, y, f2(z, rnorm(5))))
> expr[[1]]
f(x, y, f2(z, rnorm(5)))
> expr[[1]][[1]]
f
> expr[[1]][[2]]
x
> class(expr[[1]])
[1] "call"
> expr2 = parse(text = "w = f(x, y, f2(z, rnorm(5)))")
> expr2
expression(w = f(x, y, f2(z, rnorm(5))))
> expr2[[1]]
w = f(x, y, f2(z, rnorm(5)))
> expr2[[1]][[1]]
`=`
> expr2[[1]][[2]]
w
> expr2[[1]][[3]]
f(x, y, f2(z, rnorm(5)))
> 

The patterns become pretty clear quickly. This of course maps to the AST stuff discussed in that chapter of the book, but I found it personally easier to skip visualizing the expression and go straight to inspecting and manipulating it. YMMV, of course.

Best