Add 'apidoc_flag' to perlapi generation

[khwilliamson]

This is designed to make noting what flag bits a function or macro takes very easy, while helping downstream code that processes things do a better job.

• This set of changes does not require a perldelta entry.