From 729a863cb86794d985a54d557d5bee1f6e898f25 Mon Sep 17 00:00:00 2001 From: daxter154 Date: Tue, 21 Apr 2020 18:17:41 -0700 Subject: [PATCH 1/7] Styleguide First Pass First pass at styleguide for C# documentation --- STYLEGUIDE.md | 230 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 STYLEGUIDE.md diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md new file mode 100644 index 0000000..9d965c7 --- /dev/null +++ b/STYLEGUIDE.md @@ -0,0 +1,230 @@ +# Documentation Style Guide + +For those new to markdown styling, please familiarize yourself with the following [Quick reference cheat sheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet). + +**Before** starting on any work, please check the [Project Board](https://github.com/Bannerlord-Modding/Documentation/projects/1) to ensure that nobody else is working on whatever you are planning on doing. If nobody is, [create an issue](https://github.com/Bannerlord-Modding/Documentation/issues) describing what you are creating / fixing / enhancing. + +All Pull Requests are expected to match this style guide. +___ + +## Base level Structure / Navigation + +Items in the root README.md should always be nested under wider category. + +Base level items are containers for more specific items and should be linked to the root README.me. Inidvidual files (like tutorials or classes) should not be linked to the root README.md, but should be detailed the lower level files. + +``` +## [C# API Documentation](_csharp-api/) + +* [CampaignSystem](_csharp-api/campaignsystem/) +* [Core](_csharp-api/core/) +``` +All README files should only go two levels deep at *most* (but one may be more appropriate in many cases), any need to go deeper should be put into a README in the second level to avoid clutter in any single file. + +Each of the sections below would be the scope of a single readme: +``` +ROOT README +# Section (eg: api) + - packages +``` +``` +# package + - classes +``` +``` +# Class + - methods + - params +``` +Each of these READMEs should only contain the table of contents of it's relevant data. +___ + +## C# Packages + +Each package directory should contain the following sections in its README: +```md + +## Table of contents +* [classes](_csharp-api/packagename/classes/) +* [childclasses](_csharp-api/packagename/childclasses/) +* ... +## Classes +* [classname](_csharp-api/packagename/classes/classname/) +* ... +## Child Classes +* [classname](_csharp-api/packagename/childclasses/classname/) +* ... +## Template Classes +* [classname](_csharp-api/packagename/templateclasses/classname/) +* ... +## Enums +* [enumname](_csharp-api/packagename/enums/enumname/) +* ... +## Structs +* [structname](_csharp-api/packagename/structs/structname/) +* ... +## Interfaces +* [interfacename](_csharp-api/packagename/interfaces/interfacename/) +* ... +## Exception Classes +* [exceptionname](_csharp-api/packagename/exceptions/exceptionname/) +* ... +``` +>Each of the sections (at both levels) should have a valid link to their respective info pages. + +The package information header should contain the following: +```md +Current Version (Stable branch): v0.0.0.0 + +``` +___ + +## Classes (Base, Child, Templated, and Exceptions) + +Unlike the root and package level READMEs, the class README will contain more than just links to child folders. Each class will start with a **Class Overview Panel**: + +### [Parent Object Name](EXAMPLE) +# Class Name + +This is a description of the class and what it does. + + + +Using / Namespaces | | Taleworlds.Core| | | | Saveable | +:---|---|---|---|---|---|---:| +[System](EXAMPLE) | | | | | | 10000 | +[System.Xml](EXAMPLE)| +[TaleWorlds.SaveSystem](EXAMPLE) | +| + + +> Omit elements entirely if not relavent to that class (eg: parent class) + +> For the non-savable classes, use ```'color:red'``` and change to text to "Not Savable". + +After this class overview, a small code snippet should exist showing how to use / initialize the class. **This should not be exhaustive**, just a quick reference. +```csharp +new InformationMessage("Hello World!") +``` + +The above would be a valid snippet for the ```InformationMessage``` Class, but can be longer if the extra length is used to give important context about the snippet. + +Directly after this intro snippet, we have a section outlining the variables of the class. All variables are assumed to have private setters unless otherwise noted. Each variable should contain all of the following information: + +* Name +* Type (with link to that object or objects) +* Notes + +## Variables + + + +| Name | Type | Notes | +| --- | --- | --- | +| HeadArmor | int | +| MeshesMask | [SkinMask](EXAMPLE) | +| BeardCoverType | [ArmorComponent](EXAMPLE).[BeardCoverTypes](EXAMPLE) +| ReinsRopeMesh | string | returns ```this.ReinsMesh + "_rope";```| +|...|...|...| +| + + +> Always add a blank row ( | ) at the bottom of tables to square them off. Note that this table follows the same font size rules as as the class table. + +Methods should follow parameters, seperated by a H1 header. + +## Methods + + + +| Type | Method Name | # of Params | +| --- | --- | --- | --- | --- | +| void | [SetItem] | 2 | +| [Equipment](EXAMPLE) | [Clone](EXAMPLE) | 1 | +| void | [FillFrom](EXAMPLE) | 2 | +| ... | ... | ... | +| + + + +> The class page should only list out the methods like a table of contents, the detail should be saved for the methods own README page. + +Methods should be like a miniature version of a class page, with a small table at the top for parameters (if any), return type, description, etc. as shown below: + + + +### [Parent Object Name](EXAMPLE) +## Method Name + +| Parameters | Type | default | Optional? | +|---|---|---|---| +| Param Name | string | 'Hello World' | ✖ | +| Param Name | [XmlNode](EXAMPLE) | N/A | ☑ | +| ... | ... | +| + + +> Parameters should be in the same order as they appear in the method. Types should also link to their class. Copy paste symbols as needed. You don't need to link to base types (like int or string). + +### Detailed description of the method. + ___ + Code Snippets (extended) +``` +Here is how you do the thing! +``` +``` +Here is another way to do the thing +``` + +___ + +# Enums + +Enums should be placed in their own file at the Class level (on their own page under a package) with the following format: + +### [Parent Object Name](EXAMPLE) +# Enum Name + + + +Using / Namespaces | | Taleworlds.Core| | | | Flags | +:---|---|---|---|---|---|---:| +[System](EXAMPLE) | | | | | | Flag Name | +| + + +### Values +* None +* Mountable +* CanJump +* CanRear +* etc... +___ + + +# Structs + +Structs should be placed in their own file at the same level as classes and structs within their respective package (eg: TaleWorlds.Core). Due to the nature of structs, they have identical layout to classes with the only change being instead of savable, they get flags. + +## [Parent Object Name](EXAMPLE) +# Struct Name + +This is a description of the class and what it does. + + + +Using / Namespaces | | Taleworlds.Core| | | | Serializable | +:---|---|---|---|---|---|---:| +[System](EXAMPLE) | | | | | | | +| + + +> For the non-serializable classes, use ```'color:red'``` and change to text to "Not Serializable". + +Struct READMEs may have subfolders depending on their size, referr to Class layout for structs. + +___ + +## TODO: + +Style guide for Gauntlet, Tutorial, and XML docs sections \ No newline at end of file From 6bdac1febcd71b1ca4789473faf6aefa0e4c5f25 Mon Sep 17 00:00:00 2001 From: daxter154 Date: Wed, 22 Apr 2020 14:47:57 -0700 Subject: [PATCH 2/7] Typo and PR Feedback Fixes Fixed some typos, cleaned up the tables, and changed spans to divs per feedback request. Removed some overly strict requirements too. --- STYLEGUIDE.md | 43 +++++++++++++++++-------------------------- 1 file changed, 17 insertions(+), 26 deletions(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index 9d965c7..f30de09 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -88,17 +88,14 @@ Unlike the root and package level READMEs, the class README will contain more th This is a description of the class and what it does. - +
-Using / Namespaces | | Taleworlds.Core| | | | Saveable | +Using / Namespaces | |
Taleworlds.Core
| | | |
Saveable
| :---|---|---|---|---|---|---:| [System](EXAMPLE) | | | | | | 10000 | [System.Xml](EXAMPLE)| [TaleWorlds.SaveSystem](EXAMPLE) | -| - - -> Omit elements entirely if not relavent to that class (eg: parent class) +
> For the non-savable classes, use ```'color:red'``` and change to text to "Not Savable". @@ -117,7 +114,7 @@ Directly after this intro snippet, we have a section outlining the variables of ## Variables - +
| Name | Type | Notes | | --- | --- | --- | @@ -126,16 +123,13 @@ Directly after this intro snippet, we have a section outlining the variables of | BeardCoverType | [ArmorComponent](EXAMPLE).[BeardCoverTypes](EXAMPLE) | ReinsRopeMesh | string | returns ```this.ReinsMesh + "_rope";```| |...|...|...| -| - - -> Always add a blank row ( | ) at the bottom of tables to square them off. Note that this table follows the same font size rules as as the class table. +
Methods should follow parameters, seperated by a H1 header. ## Methods - +
| Type | Method Name | # of Params | | --- | --- | --- | --- | --- | @@ -143,15 +137,14 @@ Methods should follow parameters, seperated by a H1 header. | [Equipment](EXAMPLE) | [Clone](EXAMPLE) | 1 | | void | [FillFrom](EXAMPLE) | 2 | | ... | ... | ... | -| - +
> The class page should only list out the methods like a table of contents, the detail should be saved for the methods own README page. Methods should be like a miniature version of a class page, with a small table at the top for parameters (if any), return type, description, etc. as shown below: - +
### [Parent Object Name](EXAMPLE) ## Method Name @@ -161,8 +154,7 @@ Methods should be like a miniature version of a class page, with a small table a | Param Name | string | 'Hello World' | ✖ | | Param Name | [XmlNode](EXAMPLE) | N/A | ☑ | | ... | ... | -| - +
> Parameters should be in the same order as they appear in the method. Types should also link to their class. Copy paste symbols as needed. You don't need to link to base types (like int or string). @@ -185,13 +177,13 @@ Enums should be placed in their own file at the Class level (on their own page u ### [Parent Object Name](EXAMPLE) # Enum Name - +
-Using / Namespaces | | Taleworlds.Core| | | | Flags | +Using / Namespaces | |
Taleworlds.Core
| | | |
Flags
| :---|---|---|---|---|---|---:| [System](EXAMPLE) | | | | | | Flag Name | -| - +| | | | | | | Another Flag Name | +
### Values * None @@ -206,18 +198,17 @@ ___ Structs should be placed in their own file at the same level as classes and structs within their respective package (eg: TaleWorlds.Core). Due to the nature of structs, they have identical layout to classes with the only change being instead of savable, they get flags. -## [Parent Object Name](EXAMPLE) +### [Parent Object Name](EXAMPLE) # Struct Name This is a description of the class and what it does. - +
-Using / Namespaces | | Taleworlds.Core| | | | Serializable | +Using / Namespaces | |
Taleworlds.Core
| | | |
Serializable
| :---|---|---|---|---|---|---:| [System](EXAMPLE) | | | | | | | -| - +
> For the non-serializable classes, use ```'color:red'``` and change to text to "Not Serializable". From dc9e8fd3a9de43f8b49c17fdc1e19e3ef665e7f4 Mon Sep 17 00:00:00 2001 From: daxter154 Date: Wed, 22 Apr 2020 14:51:53 -0700 Subject: [PATCH 3/7] More PR Feedback fixes Adjusted Class variables table to add row for const / read only / static / etc --- STYLEGUIDE.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index f30de09..57f9637 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -116,13 +116,13 @@ Directly after this intro snippet, we have a section outlining the variables of
-| Name | Type | Notes | -| --- | --- | --- | -| HeadArmor | int | -| MeshesMask | [SkinMask](EXAMPLE) | -| BeardCoverType | [ArmorComponent](EXAMPLE).[BeardCoverTypes](EXAMPLE) -| ReinsRopeMesh | string | returns ```this.ReinsMesh + "_rope";```| -|...|...|...| +| Mod | Name | Type | Notes | +| --- | --- | --- | --- | +| Const | HeadArmor | int | +| Instance |MeshesMask | [SkinMask](EXAMPLE) | | +| ReadOnly |BeardCoverType | [ArmorComponent](EXAMPLE).[BeardCoverTypes](EXAMPLE) +| Static |ReinsRopeMesh | string | returns ```this.ReinsMesh + "_rope";```| +|...|...|...|...|
Methods should follow parameters, seperated by a H1 header. From 5c62920640526c724ff6507af33420690a07b688 Mon Sep 17 00:00:00 2001 From: daxter154 Date: Wed, 22 Apr 2020 14:56:10 -0700 Subject: [PATCH 4/7] Still more typo fixes Fixed broken Method Table --- STYLEGUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index 57f9637..3010a4d 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -133,7 +133,7 @@ Methods should follow parameters, seperated by a H1 header. | Type | Method Name | # of Params | | --- | --- | --- | --- | --- | -| void | [SetItem] | 2 | +| void | [SetItem](EXAMPLE) | 2 | | [Equipment](EXAMPLE) | [Clone](EXAMPLE) | 1 | | void | [FillFrom](EXAMPLE) | 2 | | ... | ... | ... | From 742923e2c474fb7dadfbc7d585bdc4fdb356234d Mon Sep 17 00:00:00 2001 From: daxter154 Date: Wed, 22 Apr 2020 14:57:18 -0700 Subject: [PATCH 5/7] Still more fixes More Fixes --- STYLEGUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index 3010a4d..185ab54 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -131,7 +131,7 @@ Methods should follow parameters, seperated by a H1 header.
-| Type | Method Name | # of Params | +| Type | Method Name | Number of Params | | --- | --- | --- | --- | --- | | void | [SetItem](EXAMPLE) | 2 | | [Equipment](EXAMPLE) | [Clone](EXAMPLE) | 1 | From 02d11f85b7c3b3264d67cfdadc979461b459d2be Mon Sep 17 00:00:00 2001 From: daxter154 Date: Wed, 22 Apr 2020 15:00:34 -0700 Subject: [PATCH 6/7] Last set of fixes for now Last set of fixes, removed extra table columns and more cleanup --- STYLEGUIDE.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index 185ab54..aebbc95 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -90,11 +90,11 @@ This is a description of the class and what it does.
-Using / Namespaces | |
Taleworlds.Core
| | | |
Saveable
| -:---|---|---|---|---|---|---:| -[System](EXAMPLE) | | | | | | 10000 | -[System.Xml](EXAMPLE)| -[TaleWorlds.SaveSystem](EXAMPLE) | +| Using / Namespaces |
Taleworlds.Core
|
Saveable
| +|:---|---|---:| +| [System](EXAMPLE) | | 10000 | +| [System.Xml](EXAMPLE)| | | +| [TaleWorlds.SaveSystem](EXAMPLE) | | |
> For the non-savable classes, use ```'color:red'``` and change to text to "Not Savable". @@ -132,7 +132,7 @@ Methods should follow parameters, seperated by a H1 header.
| Type | Method Name | Number of Params | -| --- | --- | --- | --- | --- | +| --- | --- | --- | | void | [SetItem](EXAMPLE) | 2 | | [Equipment](EXAMPLE) | [Clone](EXAMPLE) | 1 | | void | [FillFrom](EXAMPLE) | 2 | @@ -153,7 +153,7 @@ Methods should be like a miniature version of a class page, with a small table a |---|---|---|---| | Param Name | string | 'Hello World' | ✖ | | Param Name | [XmlNode](EXAMPLE) | N/A | ☑ | -| ... | ... | +| ... | ... | ... | ... |
> Parameters should be in the same order as they appear in the method. Types should also link to their class. Copy paste symbols as needed. You don't need to link to base types (like int or string). From ad0d63ae92e49b3af8e8236b78c6d6177a54b48b Mon Sep 17 00:00:00 2001 From: daxter154 Date: Wed, 22 Apr 2020 18:34:14 -0700 Subject: [PATCH 7/7] More feedback Fixes - still WIP Lots of feedback fixes from Anakael's feedback --- STYLEGUIDE.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index aebbc95..b633550 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -125,13 +125,13 @@ Directly after this intro snippet, we have a section outlining the variables of |...|...|...|...|
-Methods should follow parameters, seperated by a H1 header. +Methods should follow parameters, seperated by a H2 header. ## Methods
-| Type | Method Name | Number of Params | +| Type | Method Name | Params | | --- | --- | --- | | void | [SetItem](EXAMPLE) | 2 | | [Equipment](EXAMPLE) | [Clone](EXAMPLE) | 1 | @@ -149,10 +149,10 @@ Methods should be like a miniature version of a class page, with a small table a ### [Parent Object Name](EXAMPLE) ## Method Name -| Parameters | Type | default | Optional? | +| Parameters | Type | Default | |---|---|---|---| -| Param Name | string | 'Hello World' | ✖ | -| Param Name | [XmlNode](EXAMPLE) | N/A | ☑ | +| Param Name | string | 'Hello World' | +| Param Name | [XmlNode](EXAMPLE) | N/A | | ... | ... | ... | ... |
@@ -185,7 +185,7 @@ Using / Namespaces | |
Taleworlds.Core
| | | | -### Values +## Values * None * Mountable * CanJump