Dox

agileobjects · Jun 28, 2021 · 5216a50 · 5216a50
1 parent 86473e7
commit 5216a50
Show file tree

Hide file tree

Showing 9 changed files with 45 additions and 0 deletions.
diff --git a/docs/src/api/Building-Attributes.md b/docs/src/api/Building-Attributes.md
@@ -12,6 +12,7 @@ BuildableExpression.SourceCode(sc =>
     sc.AddAttribute("MyAttribute", attr =>
     {
         // Set attribute options if desired:
+        // attr.SetSummary("Attribute description");
         // attr.AddAttribute<SomeAttribute>();
         // attr.SetAbstract();
         // attr.SetSealed();
@@ -24,6 +25,7 @@ BuildableExpression.SourceCode(sc =>
 
 Members are added via the attribute API, which supports:
 
+- [Documentation](/api/Documentation)
 - [Constructors](/api/Building-Constructors)
 - [Fields](/api/Building-Fields)
 - [Properties](/api/Building-Properties)

diff --git a/docs/src/api/Building-Classes.md b/docs/src/api/Building-Classes.md
@@ -12,6 +12,7 @@ BuildableExpression.SourceCode(sc =>
     sc.AddClass("MyClass", cls =>
     {
         // Set class options if desired:
+        // cls.SetSummary("Class description");
         // cls.AddAttribute(typeof(SomeAttribute));
         // cls.SetVisibility(TypeVisibility.Internal);
         // cls.SetStatic();
@@ -26,6 +27,7 @@ BuildableExpression.SourceCode(sc =>
 
 Members are added via the class API, which supports:
 
+- [Documentation](/api/Documentation)
 - [Constructors](/api/Building-Constructors)
 - [Fields](/api/Building-Fields)
 - [Properties](/api/Building-Properties)

diff --git a/docs/src/api/Building-Enums.md b/docs/src/api/Building-Enums.md
@@ -18,6 +18,7 @@ BuildableExpression.SourceCode(sc =>
     sc.AddEnum("OddNumbers", enm =>
     {
         // Set enum options if desired:
+        // enm.SetSummary("Enum description");
         // enm.AddAttribute(typeof(SomeAttribute));
         // enm.SetVisibility(TypeVisibility.Internal);
         // enm.SetPartial();

diff --git a/docs/src/api/Building-Fields.md b/docs/src/api/Building-Fields.md
@@ -8,6 +8,7 @@ BuildableExpression.SourceCode(sc =>
         cls.AddField<string>("StringField", f =>
         {
             // Set field options if desired:
+            // f.SetSummary("Field description");
             // f.AddAttribute(typeof(SomeAttribute));
             // f.SetVisibility(MemberVisibility.Internal);
             // f.SetStatic();

diff --git a/docs/src/api/Building-Interfaces.md b/docs/src/api/Building-Interfaces.md
@@ -12,6 +12,7 @@ BuildableExpression.SourceCode(sc =>
     sc.AddInterface("IMyInterface", itf =>
     {
         // Set interface options if desired:
+        // itf.SetSummary("Interface description");
         // itf.AddAttribute<SomeAttribute>();
         // itf.SetVisibility(TypeVisibility.Internal);
         // itf.SetPartial();
@@ -23,6 +24,7 @@ BuildableExpression.SourceCode(sc =>
 
 Members are added via the interface API, which supports:
 
+- [Documentation](/api/Documentation)
 - [Properties](/api/Building-Properties)
 - [Methods](/api/Building-Methods)
 - [Attributes](/api/Building-Attributes)

diff --git a/docs/src/api/Building-Properties.md b/docs/src/api/Building-Properties.md
@@ -20,6 +20,7 @@ BuildableExpression.SourceCode(sc =>
         cls.AddProperty<int>("IntValue", p =>
         {
             // Set property options if desired:
+            // p.SetSummary("Property description");
             // p.AddAttribute(typeof(SomeAttribute));
             // p.SetVisibility(MemberVisibility.Internal);
             // p.SetStatic();

diff --git a/docs/src/api/Building-Structs.md b/docs/src/api/Building-Structs.md
@@ -12,6 +12,7 @@ BuildableExpression.SourceCode(sc =>
     sc.AddStruct("MyStruct", str =>
     {
         // Set struct options if desired:
+        // str.SetSummary("Struct description");
         // str.AddAttribute(typeof(SomeAttribute));
         // str.SetVisibility(TypeVisibility.Internal);
         // str.SetPartial();
@@ -23,6 +24,7 @@ BuildableExpression.SourceCode(sc =>
 
 Members are added via the struct API, which supports:
 
+- [Documentation](/api/Documentation)
 - [Constructors](/api/Building-Constructors)
 - [Fields](/api/Building-Fields)
 - [Properties](/api/Building-Properties)

diff --git a/docs/src/api/Documentation.md b/docs/src/api/Documentation.md
@@ -0,0 +1,33 @@
+To add a triple-slash XML documentation summary to a generated [class](/api/Building-Classes), 
+[struct](/api/Building-Struct), [interface](/api/Building-Interfaces), [enum](/api/Building-Enums), 
+[attribute](/api/Building-Attributes), [field](/api/Building-Fields), [property](/api/Building-Properties) 
+or [method](/api/Building-Methods), use:
+
+```cs
+BuildableExpression.SourceCode(sc =>
+{
+    sc.AddClass("MyClass", cls =>
+    {
+        cls.SetSummary(
+            "This is my generated class, " + 
+            "and it's pretty special");
+    });
+});
+```
+
+## File Headers
+
+To add a file header to a generated c# source code file, use:
+
+```cs
+BuildableExpression.SourceCode(sc =>
+{
+    sc.SetHeader($@"
+// - - - - - - - - - - - - - - - - - - - - -
+// This is generated code.
+// Generated on: {DateTime.Now}
+// Don't change this file directly, as your
+// changes may be overwritten.
+// - - - - - - - - - - - - - - - - - - - - -");
+});
+```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -34,5 +34,6 @@ nav:
         - Methods: api/Building-Methods.md
         - Fields: api/Building-Fields.md
         - Properties: api/Building-Properties.md
+        - Documentation: api/Documentation.md
 
 theme: readthedocs