Some improvements to the contributor's doc.
@@ -4,16 +4,16 @@ StereoKit is Open Source, so if you have changes or improvements you'd like to a
**Table of Contents**
-- Documentation
- - General Notes
- - Commentdocs
- - Samples
- - Guides
- - Screenshots
-- Project Overview
- - StereoKitC
- - StereoKit
-- Coding Guidelines
+- [Documentation](#documentation)
+ - [General Notes](#general-notes)
+ - [Commentdocs](#commentdocs)
+ - [Samples](#samples)
+ - [Documents](#documents)
+ - [Screenshots](#screenshots)
+- [Project Overview](#project-overview)
+ - [StereoKitC](#stereokitc)
+ - [StereoKit](#stereokit)
+- [Coding Guidelines](#coding-guidelines)
## Documentation
@@ -22,7 +22,7 @@ If you want to add a sample, correct some documentation, or make a guide, it's h
StereoKitDocumenter pulls documentation from a few different places when assembling the documentation site:
- Commentdocs from the C# code in [/StereoKit](/StereoKit)
-- Samples and Guides from the code in the [StereoKitTest](/Examples/StereoKitTest) project
+- Samples and Documents from the code in the [StereoKitTest](/Examples/StereoKitTest) project
- Screenshots generated by running [StereoKitTest](/Examples/StereoKitTest) in test mode
### General Notes
@@ -55,30 +55,35 @@ float distance = Vec3.Distance(pointA, pointB);
`:CodeSample:` can be followed by one or more classes, methods, fields or properties separated by spaces, so they show up as samples in more than one place.
-### Guides
+A sample should generally start with a header 3 line: `### Topic`.
-Guides are standalone documents not attached to any particular part of the API. These are great for explaining a concept, making a tutorial, or whatever else! These are also only available in the StereoKitTest project, and mostly reside over here [/Examples/StereoKitTest/Guides](/Examples/StereoKitTest/Guides).
+### Documents
-A guide uses tags similar to the way `:CodeSample:` does. It's good to note that matching samples _and_ guides are appended to eachother, so you can exclude parts of the code you don't want in the guide. Here's a small example, but check one of the existing guides as a more complete example.
+Documents are standalone pages not attached to any particular part of the API. These are great for explaining a concept, making a tutorial, or whatever else! These are also only available in the StereoKitTest project, and mostly reside over here [/Examples/StereoKitTest/Guides](/Examples/StereoKitTest/Guides).
-`:CodeSample: [Category] [Sort Index] [Name]`
+A document uses tags similar to the way `:CodeSample:` does. It's good to note that matching samples _and_ documents are appended to each other, so you can exclude parts of the code you don't want in the document. Here's a small example, but check one of the existing documents as a more complete example.
+
+`:CodeDoc: [Category] [Sort Index] [Name]`
```csharp
/// :CodeDoc: Guides 5 Drawing
/// # Drawing content with StereoKit
///
/// ...
+using StereoKit;
///
/// :End:
-// doesn't include this in the guide
+// doesn't include this in the document
namespace Guides {
/// :CodeDoc: Guides Drawing
/// ...
/// :End:
```
-`:CodeSample:` should always be followed by a category and name, but subsequent `:CodeSample:`s can omit the sort index. Note that right now, categories are only partially implemented. I'd recommend using "Guides", and add an issue if you're interested in the option for a new folder.
+`:CodeDoc:` should always be followed by a category and name, but subsequent `:CodeDoc:`s can omit the sort index. Note that right now, categories are only partially implemented. I'd recommend using "Guides", and add an issue if you're interested in the option for a new folder.
+
+A document should generally start with a header line: `# Title`.
### Screenshots
