Add function annotations and fix Clang error #1056
                
     Open
            
            
          
      
        
          +431
        
        
          −55
        
        
          
        
      
    
  
  Add this suggestion to a batch that can be applied as a single commit.
  This suggestion is invalid because no changes were made to the code.
  Suggestions cannot be applied while the pull request is closed.
  Suggestions cannot be applied while viewing a subset of changes.
  Only one suggestion per line can be applied in a batch.
  Add this suggestion to a batch that can be applied as a single commit.
  Applying suggestions on deleted lines is not supported.
  You must change the existing code in this line in order to create a valid suggestion.
  Outdated suggestions cannot be applied.
  This suggestion has been applied or marked resolved.
  Suggestions cannot be applied from pending reviews.
  Suggestions cannot be applied on multi-line comments.
  Suggestions cannot be applied while the pull request is queued to merge.
  Suggestion cannot be applied right now. Please check back later.
  
    
  
    
Hi!
This PR changes a few things to accomodate the following new annotations:
Annotations
I've overhauled the list parsing to allow for some special characters to be escaped - as I've noted in the docs.
In addition to that I've introduced a new data type for annotations called
Dict. It's a mapping of string indices to annotation values.This was necessary to accomodate the
function-arg-prefix[arg]andfunction-arg-ident-prefix[arg]annotations so that in a function likeannotations to arguments can simply be created by adding
cbindgen:function-arg-prefix[bar]. I much prefer this over indexing by number since that might inadvertently add the annotation to another argument if they're ever shifted around.As a part of these changes I've added the
CFuncArgstruct to replace the previous tuple. Initially this was because I placed theident_prefixthere but it turned out to be easier to just reuse the one onCDecl.These annotations allow specifying SAL annotations, Compiler-specific attributes (e.g. Clang) and macros in general.
Clang errors
The body example added an
inline void foo()tobody.compat.cwhich caused a compiler error in conjunction with-Wnon-c-typedef-for-linkagesince the generated structs were untagged. This effectively broke the automated test suite for me.I've changed it so that if cbindgen is generating C++ with C compatibility and the user adds anything using
[export.body]or[export.pre_body]cbindgen will enforce tags for those structs.Function affixes
The remaining annotations provide similar benefits but for functions.
Outlook
This PR lays the foundation for solving #982. For more advanced use-cases the annotations defined in this PR should still be available but hidden behind an abstraction layer for e.g.
NonNullparameters.