Skip to content

Commit 5fd22ad

Browse files
committed
Work on an outline for two new generator docs pages
1 parent 669c235 commit 5fd22ad

2 files changed

Lines changed: 53 additions & 0 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Generator Mods
2+
3+
(TODO: Explain what mods are)
4+
5+
(TODO: Add a section for each mod and explain what they do at a high level. Also provide examples of the transformations done. Also link to where more information can be obtained (source code, test cases))
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
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

Comments
 (0)