Should I ever include that local variable, or any local variable ever in a header?
The only case I can think of is if you write an inline or a template function: For those, the function/method body should be in the header. Then, obviously, local variables are in the header, too.
If not, should I ever document it in the header?
There might be rare instances when a caller must know about a local variable of a function. E.g. if stack space is scarce and the function uses a 100k local array variable. Or if it's a template function that non-obviously creates an instance of its template parameter - that information might be important to the caller.
But those are extreme and construed edge cases. In the general case, the header should only document the external "contract" your functions offer, behavior that the caller can rely on even in future versions of the code.
I guess another way to ask this, is if a variable that I am using is only used in one function; should I always just make it a local variable, or are there cases where that variable should be made a member?
As @Brandin said: You would make it a member, if you the need to preserve state between different calls.
However, it might be a cleaner design to split that member and function off into a separate class, and have a member of that class instead:
// or even:
That way it's clear that:
- the "function"
Bar retains state between calls
- the member
localFlag is meant to be private to