Address Pull Request Feedback

- Rename IOdataAnnotable -> IODataAnnotable - Merged SampleJsonGenerator into ODataParser - Added command line parameter for resource file template - Extended ParameterDataType to support getting the MarkDown -
OneDrive · Jun 5, 2017 · 40b7a3b · 40b7a3b
1 parent e81f9e4
commit 40b7a3b
Show file tree

Hide file tree

Showing 21 changed files with 168 additions and 118 deletions.
diff --git a/ApiDocs.Console/CommandLineOptions.cs b/ApiDocs.Console/CommandLineOptions.cs
@@ -549,5 +549,7 @@ public enum PublishFormat
 
     class GenerateDocsOptions : CheckMetadataOptions
     {
+        [Option("resource-template", HelpText = "Specifies the path to a mustache template file to use for generating documentation for resources (complex and entity types)", Required = false)]
+        public string ResourceTemplateFile { get; set; }
     }
 }
diff --git a/ApiDocs.Console/Program.cs b/ApiDocs.Console/Program.cs
@@ -1501,7 +1501,7 @@ private static async Task<bool> GenerateDocsAsync(GenerateDocsOptions options)
 
             FancyConsole.WriteLine(FancyConsole.ConsoleSuccessColor, "  found {0} schema definitions: {1}", ef.DataServices.Schemas.Count, (from s in ef.DataServices.Schemas select s.Namespace).ComponentsJoinedByString(", "));
 
-            DocumentationGenerator docGenerator = new DocumentationGenerator();
+            DocumentationGenerator docGenerator = new DocumentationGenerator(options.ResourceTemplateFile);
             docGenerator.GenerateDocumentationFromEntityFrameworkAsync(ef, options.DocumentationSetPath);
 
             return true;

diff --git a/ApiDocs.DocumentationGeneration.UnitTests/DocumentationTestBase.cs b/ApiDocs.DocumentationGeneration.UnitTests/DocumentationTestBase.cs
@@ -93,7 +93,7 @@ protected void AddProperty(ComplexType ct, string name, string type = "Edm.Strin
 
         protected ComplexType GetComplexType(Schema schema, string name, string inlineDescription = null, string schemaDescription = null)
         {
-            ComplexType ct = new ComplexType { Name = name };
+            ComplexType ct = new ComplexType { Name = name, Namespace = schema.Namespace};
             if (inlineDescription != null)
             {
                 ct.Annotation.Add(this.GetDescriptionAnnotation(inlineDescription));
@@ -117,7 +117,7 @@ protected Annotation GetDescriptionAnnotation(string description)
 
         protected EntityType GetEntityType(Schema schema, string name, string inlineDescription = null, string schemaDescription = null)
         {
-            EntityType et = new EntityType { Name = name };
+            EntityType et = new EntityType { Name = name, Namespace = schema.Namespace};
             if (inlineDescription != null)
             {
                 et.Annotation.Add(this.GetDescriptionAnnotation(inlineDescription));

diff --git a/ApiDocs.DocumentationGeneration.UnitTests/PropertyTests.cs b/ApiDocs.DocumentationGeneration.UnitTests/PropertyTests.cs
@@ -50,6 +50,23 @@ public void PropertyTableEntryIsCorrectlyFormattedForComplexType()
             Assert.IsTrue(markDown.Contains(expected), "Generated markdown should contain '{0}' Actual:\n{1}", expected, markDown);
         }
 
+        [Test]
+        public void PropertyTableEntryIsCorrectlyFormattedForComplexTypeCollection()
+        {
+            string propertyType = "propertyComplexType";
+            ComplexType ct = this.GetComplexType(this.schema, "test");
+            ComplexType ct2 = this.GetComplexType(this.schema, "propertyComplexType");
+            string description = "Inline property description";
+            string propertyName = "ComplexProperty";
+            this.AddProperty(ct, propertyName, type: $"Collection({this.schema.Namespace}.{propertyType})", inlineDescription: description);
+
+            string expected = $"|{propertyName}|[{propertyType}]({propertyType}.md) collection|{description}|";
+
+            string markDown = this.documentationGenerator.GetMarkDownForType(this.entityFramework, ct);
+
+            Assert.IsTrue(markDown.Contains(expected), "Generated markdown should contain '{0}' Actual:\n{1}", expected, markDown);
+        }
+
         [Test]
         public void PropertyTableEntryIsCorrectlyFormattedForPrimitiveType()
         {
@@ -63,5 +80,19 @@ public void PropertyTableEntryIsCorrectlyFormattedForPrimitiveType()
 
             Assert.IsTrue(markDown.Contains(expected), "Generated markdown should contain '{0}' Actual:\n{1}", expected, markDown);
         }
+
+        [Test]
+        public void PropertyTableEntryIsCorrectlyFormattedForPrimitiveTypeCollection()
+        {
+            string description = "Inline property description";
+            string propertyType = "Boolean";
+            string propertyName = "PrimitiveProperty";
+            string expected = $"|{propertyName}|{propertyType} collection|{description}|";
+            ComplexType ct = this.GetComplexType(this.schema, "Test");
+            this.AddProperty(ct, propertyName, type: $"Collection(Edm.{propertyType})", inlineDescription: description);
+            string markDown = this.documentationGenerator.GetMarkDownForType(this.entityFramework, ct);
+
+            Assert.IsTrue(markDown.Contains(expected), "Generated markdown should contain '{0}' Actual:\n{1}", expected, markDown);
+        }
     }
 }
diff --git a/ApiDocs.DocumentationGeneration/ApiDocs.DocumentationGeneration.csproj b/ApiDocs.DocumentationGeneration/ApiDocs.DocumentationGeneration.csproj
@@ -61,7 +61,6 @@
       <DesignTime>True</DesignTime>
       <DependentUpon>Templates.resx</DependentUpon>
     </Compile>
-    <Compile Include="SampleJsonGenerator.cs" />
   </ItemGroup>
   <ItemGroup>
     <None Include="packages.config">

diff --git a/ApiDocs.DocumentationGeneration/DocumentationGenerator.cs b/ApiDocs.DocumentationGeneration/DocumentationGenerator.cs
@@ -42,13 +42,29 @@ public class DocumentationGenerator
     {
         private readonly Generator resourceMarkDownGenerator;
 
-        public DocumentationGenerator()
+        public DocumentationGenerator() : this(null)
+        {
+        }
+
+        public DocumentationGenerator(string resourceTemplateFile)
         {
             string template = null;
-            using (var ms = new MemoryStream(Templates.resource))
-            using (var reader = new StreamReader(ms))
+
+            if (string.IsNullOrWhiteSpace(resourceTemplateFile))
+            {
+                using (var ms = new MemoryStream(Templates.resourceMarkDown))
+                using (var reader = new StreamReader(ms))
+                {
+                    template = reader.ReadToEnd();
+                }
+            }
+            else
             {
-                template = reader.ReadToEnd();
+                if (!File.Exists(resourceTemplateFile))
+                {
+                    throw new FileNotFoundException($"Resource MarkDown template not found", resourceTemplateFile);
+                }
+                template = File.ReadAllText(resourceTemplateFile);
             }
 
             if (string.IsNullOrWhiteSpace(template))

diff --git a/ApiDocs.DocumentationGeneration/Extensions/DocumentationExtensions.cs b/ApiDocs.DocumentationGeneration/Extensions/DocumentationExtensions.cs
@@ -91,7 +91,7 @@ public static List<Annotation> GetAnnotationsForProperty(this Property targetPro
             return new List<Annotation>();
         }
 
-        public static List<Annotation> GetAnnotationsForTarget<T>(this T target, EntityFramework entityFramework) where T: IODataNavigable, IOdataAnnotatable
+        public static List<Annotation> GetAnnotationsForTarget<T>(this T target, EntityFramework entityFramework) where T: IODataNavigable, IODataAnnotatable
         {
             string targetType = entityFramework.LookupIdentifierForType(target);
             var targetNamespace = targetType.NamespaceOnly();

diff --git a/ApiDocs.DocumentationGeneration/Model/DocumentationComplexType.cs b/ApiDocs.DocumentationGeneration/Model/DocumentationComplexType.cs
@@ -39,9 +39,9 @@ public DocumentationComplexType(EntityFramework entityFramework, ComplexType com
         {
             this.Name = complexType.Name;
             this.Description = complexType.GetDescription(entityFramework);
-            this.Namespace = entityFramework.LookupIdentifierForType(complexType).NamespaceOnly();
+            this.Namespace = complexType.Namespace;
             this.Properties = complexType.Properties.Select(p => p.ToDocumentationProperty(entityFramework, complexType)).ToList();
-            this.Json = SampleJsonGenerator.GetSampleJson(entityFramework, complexType).ToString(Formatting.Indented);
+            this.Json = ODataParser.BuildJsonExample(complexType, entityFramework.DataServices.Schemas);//SampleJsonGenerator.GetSampleJson(entityFramework, complexType).ToString(Formatting.Indented);
 
 
             if (complexType.BaseType != null)

diff --git a/ApiDocs.DocumentationGeneration/Model/DocumentationProperty.cs b/ApiDocs.DocumentationGeneration/Model/DocumentationProperty.cs
@@ -23,6 +23,8 @@
  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+using ApiDocs.Validation;
+
 namespace ApiDocs.DocumentationGeneration.Model
 {
     using System.Collections.Generic;
@@ -35,14 +37,33 @@ public class DocumentationProperty
         public DocumentationProperty(EntityFramework entityFramework, ComplexType complexType, Property property)
         {
             this.Name = property.Name;
-            this.Type = property.GetTypeNameMarkdown(entityFramework);
+
+            string typeName = property.Type;
+            bool isCollection = property.Type.IsCollection();
+            if (isCollection)
+            {
+                typeName = property.Type.ElementName();
+            }
+
+            var simpleType = typeName.ToODataSimpleType();
+            if (simpleType != SimpleDataType.None)
+            {
+                this.Type = new ParameterDataType(simpleType, isCollection);
+            }
+            else
+            {
+                this.Type = new ParameterDataType(typeName, isCollection);
+            }
+            this.TypeMarkDown = this.Type.GetMarkDown();
             this.Description = property.GetDescription(entityFramework, complexType);
         }
 
         public string Description { get; private set; }
 
         public string Name { get; private set; }
 
-        public string Type { get; private set; }
+        public ParameterDataType Type { get; private set; }
+
+        public string TypeMarkDown { get; private set; }
     }
 }
diff --git a/ApiDocs.DocumentationGeneration/Properties/Templates.Designer.cs b/ApiDocs.DocumentationGeneration/Properties/Templates.Designer.cs
diff --git a/ApiDocs.DocumentationGeneration/Properties/Templates.resx b/ApiDocs.DocumentationGeneration/Properties/Templates.resx
@@ -118,7 +118,7 @@
     <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
   </resheader>
   <assembly alias="System.Windows.Forms" name="System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
-  <data name="resource" type="System.Resources.ResXFileRef, System.Windows.Forms">
+  <data name="resourceMarkDown" type="System.Resources.ResXFileRef, System.Windows.Forms">
     <value>..\templates\resource.md.mustache;System.Byte[], mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
   </data>
 </root>
diff --git a/ApiDocs.DocumentationGeneration/SampleJsonGenerator.cs b/ApiDocs.DocumentationGeneration/SampleJsonGenerator.cs
diff --git a/ApiDocs.DocumentationGeneration/Templates/resource.md.mustache b/ApiDocs.DocumentationGeneration/Templates/resource.md.mustache
@@ -12,13 +12,13 @@
 
 | Name | Type | Description |
 |:---|:---|:---|
-{{#each Properties}}|{{Name}}|{{Type}}|{{Description}}|
+{{#each Properties}}|{{Name}}|{{TypeMarkDown}}|{{Description}}|
 {{/each}}{{/if}}{{#if NavigationProperties}}
 ## Relationships
 
 | Name | Type | Description |
 |:---|:---|:---|
-{{#each NavigationProperties}}|{{Name}}|{{Type}}|{{Description}}|
+{{#each NavigationProperties}}|{{Name}}|{{TypeMarkDown}}|{{Description}}|
 {{/each}}{{/if}}
 ## JSON representation
 

diff --git a/ApiDocs.Publishing/CSDL/CsdlWriter.cs b/ApiDocs.Publishing/CSDL/CsdlWriter.cs
@@ -755,7 +755,7 @@ private void MergeInstanceAnnotationsAndRecordTerms(string typeName, IEnumerable
             return prop;
         }
 
-        private static void AddDescriptionAnnotation<T>(string typeName, T targetProperty, ParameterDefinition sourceParameter, string termForDescription = Term.LongDescriptionTerm) where T: Property, IOdataAnnotatable
+        private static void AddDescriptionAnnotation<T>(string typeName, T targetProperty, ParameterDefinition sourceParameter, string termForDescription = Term.LongDescriptionTerm) where T: Property, IODataAnnotatable
         {
             if (!string.IsNullOrEmpty(sourceParameter.Description))
             {

diff --git a/ApiDocs.Validation/OData/ComplexType.cs b/ApiDocs.Validation/OData/ComplexType.cs
@@ -34,7 +34,7 @@ namespace ApiDocs.Validation.OData
     using Transformation;
 
     [XmlRoot("ComplexType", Namespace = ODataParser.EdmNamespace)]
-    public class ComplexType : XmlBackedTransformableObject, IODataNavigable, IOdataAnnotatable
+    public class ComplexType : XmlBackedTransformableObject, IODataNavigable, IODataAnnotatable
     {
         public ComplexType()
         {
@@ -112,5 +112,8 @@ public override void ApplyTransformation(BaseModifications mods, EntityFramework
         [XmlIgnore]
         public override string ElementIdentifier { get { return this.Name; } set { this.Name = value; } }
 
+        [XmlIgnore]
+        public string Namespace { get; set; }
+
     }
 }
diff --git a/ApiDocs.Validation/OData/EnumType.cs b/ApiDocs.Validation/OData/EnumType.cs
@@ -31,7 +31,7 @@ namespace ApiDocs.Validation.OData
     using Transformation;
 
 	[XmlRoot("EnumType", Namespace = ODataParser.EdmNamespace)]
-    public class EnumType : XmlBackedTransformableObject, IOdataAnnotatable, IODataNavigable
+    public class EnumType : XmlBackedTransformableObject, IODataAnnotatable, IODataNavigable
     {
         public EnumType()
         {

diff --git a/ApiDocs.Validation/OData/ExtensionMethods.cs b/ApiDocs.Validation/OData/ExtensionMethods.cs
@@ -23,6 +23,8 @@
  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+using System.ComponentModel;
+
 namespace ApiDocs.Validation.OData
 {
     using System;
@@ -313,5 +315,20 @@ public static SimpleDataType ToODataSimpleType(this string typeName)
             return SimpleDataType.Object;
         }
 
+        public static bool IsCollection(this string typeName)
+        {
+            return typeName.StartsWith($"{ODataParser.CollectionPrefix}", StringComparison.Ordinal) && typeName.EndsWith(")", StringComparison.Ordinal);
+        }
+
+        public static string ElementName(this string collection)
+        {
+            if (!collection.IsCollection())
+            {
+                throw new ArgumentOutOfRangeException(nameof(collection), $"'{collection}' is not a collction.");
+            }
+
+            return collection.Substring(ODataParser.CollectionPrefix.Length, collection.Length - ODataParser.CollectionPrefix.Length -1);
+        }
+
     }
 }
diff --git a/ApiDocs.Validation/OData/IOdataAnnotatable.cs b/ApiDocs.Validation/OData/IOdataAnnotatable.cs
@@ -30,7 +30,7 @@ namespace ApiDocs.Validation.OData
     /// <summary>
     /// Interface for elements that can be annotated;
     /// </summary>
-    public interface IOdataAnnotatable : IODataNamedElement
+    public interface IODataAnnotatable : IODataNamedElement
     {
         List<Annotation> Annotation { get; set; }
     }