|
| 1 | +# Name Processing and Prettification |
| 2 | + |
| 3 | +A primary goal of Silk.NET is to provide a first-class .NET experience for the bindings that it provides. |
| 4 | + |
| 5 | +One such way that Silk.NET achieves this is by transforming native identifiers into identifiers that follow the |
| 6 | +Microsoft Framework Design guidelines. |
| 7 | +Of these guidelines, most notable are the guidelines relating to capitalization. |
| 8 | + |
| 9 | +Naming Guidelines: https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines |
| 10 | + |
| 11 | +Capitalization Conventions: https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/capitalization-conventions |
| 12 | + |
| 13 | +## High-Level Overview |
| 14 | + |
| 15 | +This section explains how names flow through the SilkTouch generator pipeline: |
| 16 | + |
| 17 | +1. Names enter the pipeline from native sources (eg: C header files) |
| 18 | + - Eg: `` |
| 19 | +2. Mods add metadata to each name as C# attributes. |
| 20 | + - Eg: `[NativeName]`, `[NameAffix]` |
| 21 | +3. `PrettifyNames` uses the metadata to transform the names according to user-provided configuration. |
| 22 | +4. Metadata is stripped from the generated bindings. |
| 23 | + |
| 24 | +(TODO: Elaborate more and provide examples) |
| 25 | + |
| 26 | +## PrettifyNames |
| 27 | + |
| 28 | +(TODO: Explain how PrettifyNames is the mod central to name processing) |
| 29 | + |
| 30 | +## Name Splitting |
| 31 | + |
| 32 | +(TODO: Explain how name splitting works, relate it to tokenization. Explain decisions like why "2D" is split as "2_D") |
| 33 | + |
| 34 | +## Name Prettification |
| 35 | + |
| 36 | +(TODO: Explain how prettification works alongside name splitting. Explain how acronyms are handled. Explain why number fragments are merged to preceding letter fragments and how this affects acronyms and pascal casing.) |
| 37 | + |
| 38 | +## Name Affixes |
| 39 | + |
| 40 | +(TODO: Explain the motivation behind this system. Explain that users configure how name affixes are processed while mods identify affixes (separation of concerns).) |
| 41 | + |
| 42 | +### Referenced Affixes |
| 43 | + |
| 44 | +(TODO: Explain why referenced affixes exist (compound names and types that are the logical extensions of other types) and when these are used in the generator. Explain how these are processed.) |
| 45 | + |
| 46 | +### Affix Categories |
| 47 | + |
| 48 | +(TODO: Exhaustively list each category being used in the generator. Explain which mods add the affix category. Provide examples on what the affixes look like. Provide recommendations on how each affix should be configured (i.e., should match the configuration used by `generator.json`).) |
0 commit comments