bump_global_ctr_for_cur_func: Increment a global counter specific to the current function
In langfob/docaids: Package For Helping Document Local Variables In R

Description Usage Arguments Details Value Choice of default sys.call_ht Possible (though unlikely) problems See Also

This function creates a global counter for a function if that counter doesn't exist yet. If it already exists, then it increments that counter. This is primarily used to help doc_vars_in_this_func_once determine whether to call doc_vars_in_this_func. This is because you usually don't want to call the documenter more than once, no matter how often the function it's documenting is called.

1 2	bump_global_ctr_for_cur_func(sys.call_ht = -7, ctr_name_prefix = "TEMPCTR___RM_THIS_AT_END__")

`sys.call_ht`	negative integer to pass to sys.call() to specify how high to look on the `sys.call` stack.
`ctr_name_prefix`	character string to prepend to function name when building a counter name that is supposed to be unique

This function creates what is hoped to be a unique name for the counter based on the name of the function, i.e., it prepends a copy of the function's name with a strange string. That prepend string is "TEMPCTR___RM_THIS_AT_END__". If the function being documented was called func1, then the resulting counter's name would be "TEMPCTR___RM_THIS_AT_END__func1".

integer value of global counter for the current function

The default value for sys.call_ht has been set to -7 as a result of much trial and error to find what height landed on the right call in the stack. Be very careful if you give it a different value.

This method of creating names for counters is not foolproof, but it's good enough for the quick hacking of documentation aids that this code is intended to support. There are at least two ways that it might screw up, but each has a fix.

Name matches a name in user's code: If the user's code contained a name matching the very strange generated name, the ctr_name_prefix can be set in the argument list.
Generic function: There may be different versions of the same generic function in use at the same time and they will all end up being counted as the same function since the generated name will be the same. In this case, one solution is to pass in a different unique ctr_name_prefix in the call in each of the different uses of the generic. Depending on how long it takes for the program to run, it may be simpler to just re-run the whole program with the call cut and pasted into each different form of the generic each time the program is re-run; not pretty, but perhaps the least trouble in the end.

remove_global_ctrs_if_desired for cleanup of counters at end of run

langfob/docaids documentation built on May 20, 2019, 7:56 p.m.