Add inline docs in C headers

[sffc]

From @dminor in unicode-org/icu4x#1269 (comment):

Is it intentional for the C++ headers to include comments, but not the C headers? It makes sense that the copies of the C headers in ffi/diplomat/cpp are just an implementation detail of the C++ headers, but the same argument doesn't seem to hold for ffi/diplomat/c.

Note: @gregtatum added C++ docs generation in #85. The primary documentation is intended to be the *.rst files, but perhaps we should put the docs into the *.h files as well.

[gregtatum]

Yeah, this would be really nice for in-editor hints. There was no particularly reason for not doing C headers, other than it was more work that just doing C++ headers.