Arg definitions added to states.file.append

Closes #2684

@whiteinge - can you take a look at these argument specifications and make sure everything makes sense? A lot people have written code in this function, but it looks like you did the original documentation for examples and such.