Skip to content

Commit

Permalink
Update HowMade.md
Browse files Browse the repository at this point in the history
Clarified process, and corrected  step numbering to account for the newly inserted step (3).
  • Loading branch information
schlosrat authored Jul 24, 2023
1 parent 6d72768 commit 6f645aa
Showing 1 changed file with 3 additions and 3 deletions.
6 changes: 3 additions & 3 deletions docfx_project/articles/HowMade.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,13 @@ dotnet tool install -g BepInEx.AssemblyPublicizer.Cli
assembly-publicizer ./Assembly-CSharp.dll --strip-only
```
2. **Produce a Stripped Project**. Using the stripped version of the Assembly-CSharp.dll generated in Step 1 it's possible to create a C# project from that DLL. This is the step that produces the initial set of .cs files to which we may manually add triple slash (///) comments. There are several ways to do this, one being to load the stripped DLL into [JetBrains dotPeek](https://www.jetbrains.com/decompiler/) and use that tool to create a new Visual Studio project. **NOTE**: As the input is a *stripped DLL*, we're not in fact decompiling the game, and thus the output does not contain any actual internal game code. What we do capture are namespaces, method interfaces, class definitions, etc. Everything we need for the API documentation and nothing we're forbidden from sharing.
3. Manually add triple slash comments to the code capturing insights gleaned from modding to clarify the understood purpose and use of API objects. You can skip this step the first time you do this and you'll still get a useful set of API documentation, however on subsequent iterations this is the point where you will want to merge in any manually inserted comments which were added to the previous iteration to preserve that knowledge. If, at some point, the devs share their own XML docs, then this would be the point to merge those in.
4. **Generate an XML Documentation File**. Using the stripped project generated in Step 2 it's possible to produce an Assembly-CSharp.xml file that is useful both for IntelliSense documentation while modding and as an input to DocFX to supply the unofficial comments to go with the stripped DLL. This can be done using a variety of methods, one being [GenDoc](https://github.com/jan-bures/GenDoc), which is an open-source Roslyn API tool that can open a .sln file you point it to, and for each project that's in it, it goes through all the types and members and generates their XML documentation into a file per project.
3. **Manually add triple slash comments**. Using the stripped .cs files produced in Step 2 manually add triple slash comments to the code capturing insights gleaned from modding to clarify the understood purpose and use of API objects. You can skip this step the first time you do this and you'll still get a useful set of API documentation, however on subsequent iterations this is the point where you will want to merge in any manually inserted comments which were added to the previous iteration to preserve that knowledge. If, at some point, the devs share their own XML docs, then this would be the point to merge those in.
4. **Generate an XML Documentation File**. Using the stripped project generated in Step 3 it's possible to produce an Assembly-CSharp.xml file that is useful both for IntelliSense documentation while modding and as an input to DocFX to supply the unofficial comments to go with the stripped DLL. This can be done using a variety of methods, one being [GenDoc](https://github.com/jan-bures/GenDoc), which is an open-source Roslyn API tool that can open a .sln file you point it to, and for each project that's in it, it goes through all the types and members and generates their XML documentation into a file per project.
GenDoc is called from the command line and takes two arguments, the path to the .sln file and the output folder in which to deposit the resulting XML files. In this case, there will be just one XML file, Assembly-CSharp.xml, and we want it to be located in the same folder along with the stripped version of Assembly-CSharp.dll. Here is the command used to do this which looks for the stripped project from Step 2 in the src_stripped folder and will place the resulting Assembly-CSharp.xml file in the DLL_stripped folder. If any of the stripped .cs files have been modified to include documentation-generating comments (///), then those will be captured in the Assembly-CSharp.xml file.
```
GenDoc src_stripped\Assembly-CSharp_stripped.sln DLL_Stripped
```
4. **Generate DocFX API Documentation Site**. Using the stripped DLL from Step 1 and the resulting XMl from Step 3, it's possible to generate useful API documentation using [DocFX](https://dotnet.github.io/docfx/index.html). This process requires 4 sub-steps. 1. Install DocFx, 2. Build a docfx_project, 3. Edit the docfx.json file, and 4. Generate the DocFX site files. The first two steps are as follows.
4. **Generate DocFX API Documentation Site**. Using the stripped DLL from Step 1 and the resulting XMl from Step 4, it's possible to generate useful API documentation using [DocFX](https://dotnet.github.io/docfx/index.html). This process requires 4 sub-steps. 1. Install DocFx, 2. Build a docfx_project, 3. Edit the docfx.json file, and 4. Generate the DocFX site files. The first two steps are as follows.
```
dotnet tool update -g docfx
docfx init --quiet
Expand Down

0 comments on commit 6f645aa

Please sign in to comment.