feat: Add nullable annotation

Add C# 8 nullable annotations

See pull request #15 from ap0llo/features/nullable-reference-types

docs/apireference/Grynwald/MarkdownGenerator/MdSpan/operators/Implicit.md

@@ -14,6 +14,10 @@ public static implicit operator MdSpan(string text);
 
 The string value to wrap in a span.
 
+## Remarks
+
+Wraps a string in an instance of [MdTextSpan](../../MdTextSpan/index.md). Although the nullable annotations do not indicate it, passing in `null` will return `null`.
+
 ## Returns
 
 [MdSpan](../index.md)

docs/apireference/Grynwald/MarkdownGenerator/MdTextSpan/operators/Implicit.md

@@ -14,6 +14,10 @@ public static implicit operator MdTextSpan(string text);
 
 The string value to wrap in an instance of [MdTextSpan](../index.md)
 
+## Remarks
+
+Wraps a string in an instance of [MdTextSpan](../index.md). Although the nullable annotations do not indicate it, passing in `null` will return `null`.
+
 ## Returns
 
 [MdTextSpan](../index.md)

src/Directory.Build.props

@@ -15,7 +15,8 @@
 
 
 	<PropertyGroup>
-		<LangVersion>7.2</LangVersion>
+		<LangVersion>8.0</LangVersion>
+		<Nullable>enable</Nullable>
 		<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
 	</PropertyGroup>
 

src/MarkdownGenerator.Test.DocsVerification/Infrastructure/CodeSample.cs

@@ -15,7 +15,8 @@ public sealed class CodeSample : IXunitSerializable
         // parameterless constructor required for deserialization by xunit
         public CodeSample()
         {
-
+            RelativePath = null!;  // Set by Deserialize();
+            SourceCode = null!;    // Set by Deserialize();
         }
 
         public CodeSample(string relativePath, int line, string code)

src/MarkdownGenerator.Test/Internal/_DocumentSerializer/DocumentSerializerTest.cs

@@ -959,7 +959,7 @@ public void EmptyBlock_is_seralized_as_expected() =>
             AssertToStringEquals("", new MdDocument(MdEmptyBlock.Instance));
 
 
-        private void AssertToStringEquals(string expected, MdDocument document, MdSerializationOptions options = null)
+        private void AssertToStringEquals(string expected, MdDocument document, MdSerializationOptions? options = null)
         {
             using (var writer = new StringWriter())
             {

src/MarkdownGenerator.Test/_Model/DocumentSetTest.cs

@@ -29,7 +29,7 @@ public void Indexer_returns_expected_document()
         public void Indexer_throws_ArgumentNullException_if_path_is_null()
         {
             var set = new DocumentSet<TestDocument>();
-            Assert.Throws<ArgumentNullException>(() => set[(string)null]);
+            Assert.Throws<ArgumentNullException>(() => set[(string)null!]);
         }
 
         [Fact]
@@ -56,7 +56,7 @@ public void Indexer_returns_a_documents_path()
         public void Indexer_throws_ArgumentNullException_if_document_is_null()
         {
             var set = new DocumentSet<TestDocument>();
-            Assert.Throws<ArgumentNullException>(() => set[(TestDocument)null]);
+            Assert.Throws<ArgumentNullException>(() => set[(TestDocument)null!]);
         }
 
         [Fact]

src/MarkdownGenerator.Test/_Model/MdDocumentSetTest.cs

@@ -23,7 +23,7 @@ public void Indexer_returns_expected_document()
         public void Indexer_throws_ArgumentNullException_if_path_is_null()
         {
             var set = new MdDocumentSet();
-            Assert.Throws<ArgumentNullException>(() => set[(string)null]);
+            Assert.Throws<ArgumentNullException>(() => set[(string)null!]);
         }
 
         [Fact]
@@ -49,7 +49,7 @@ public void Indexer_returns_a_documents_path()
         public void Indexer_throws_ArgumentNullException_if_document_is_null()
         {
             var set = new MdDocumentSet();
-            Assert.Throws<ArgumentNullException>(() => set[(MdDocument)null]);
+            Assert.Throws<ArgumentNullException>(() => set[(MdDocument)null!]);
         }
 
         [Fact]

src/MarkdownGenerator.Test/_Model/_Blocks/MdBlockQuoteTest.cs

@@ -34,11 +34,11 @@ public void MdBlockQuote_can_be_initialized_with_string_content_02()
             var compositeSpan = (MdCompositeSpan)paragraph.Text;
 
             Assert.Equal(2, compositeSpan.Spans.Count);
-            Assert.IsType<MdTextSpan>(compositeSpan.Spans[0]);
-            Assert.IsType<MdTextSpan>(compositeSpan.Spans[1]);
+            var textSpan1 = Assert.IsType<MdTextSpan>(compositeSpan.Spans[0]);
+            var textSpan2 = Assert.IsType<MdTextSpan>(compositeSpan.Spans[1]);
 
-            Assert.Equal("Content1", (compositeSpan.Spans[0] as MdTextSpan).Text);
-            Assert.Equal("Content2", (compositeSpan.Spans[1] as MdTextSpan).Text);
+            Assert.Equal("Content1", textSpan1.Text);
+            Assert.Equal("Content2", textSpan2.Text);
         }
 
         [Fact]

src/MarkdownGenerator.Test/_Model/_Blocks/MdListItemTest.cs

@@ -34,11 +34,11 @@ public void MdListItem_can_be_initialized_with_string_content_02()
             var compositeSpan = (MdCompositeSpan)paragraph.Text;
 
             Assert.Equal(2, compositeSpan.Spans.Count);
-            Assert.IsType<MdTextSpan>(compositeSpan.Spans[0]);
-            Assert.IsType<MdTextSpan>(compositeSpan.Spans[1]);
+            var textSpan1 = Assert.IsType<MdTextSpan>(compositeSpan.Spans[0]);
+            var textSpan2 = Assert.IsType<MdTextSpan>(compositeSpan.Spans[1]);
 
-            Assert.Equal("Content1", (compositeSpan.Spans[0] as MdTextSpan).Text);
-            Assert.Equal("Content2", (compositeSpan.Spans[1] as MdTextSpan).Text);
+            Assert.Equal("Content1", textSpan1.Text);
+            Assert.Equal("Content2", textSpan2.Text);
         }
 
         [Fact]

src/MarkdownGenerator.Test/_Model/_Blocks/MdParagraphTest.cs

@@ -25,11 +25,11 @@ public void MdParagraph_can_be_initialized_with_string_content_02()
             var compositeSpan = (MdCompositeSpan)paragraph.Text;
 
             Assert.Equal(2, compositeSpan.Spans.Count);
-            Assert.IsType<MdTextSpan>(compositeSpan.Spans[0]);
-            Assert.IsType<MdTextSpan>(compositeSpan.Spans[1]);
+            var textSpan1 = Assert.IsType<MdTextSpan>(compositeSpan.Spans[0]);
+            var textSpan2 = Assert.IsType<MdTextSpan>(compositeSpan.Spans[1]);
 
-            Assert.Equal("Content1", (compositeSpan.Spans[0] as MdTextSpan).Text);
-            Assert.Equal("Content2", (compositeSpan.Spans[1] as MdTextSpan).Text);
+            Assert.Equal("Content1", textSpan1.Text);
+            Assert.Equal("Content2", textSpan2.Text);
         }
 
 

src/MarkdownGenerator.Test/_Model/_Blocks/MdTableRowTest.cs

@@ -67,11 +67,11 @@ public void MdTableRow_can_be_initialized_with_string_content_02()
             var singleLineSpan1 = (MdSingleLineSpan)row[0];
             var singleLineSpan2 = (MdSingleLineSpan)row[1];
 
-            Assert.IsType<MdTextSpan>(singleLineSpan1.Content);
-            Assert.IsType<MdTextSpan>(singleLineSpan2.Content);
+            var textSpan1 = Assert.IsType<MdTextSpan>(singleLineSpan1.Content);
+            var textSpan2 = Assert.IsType<MdTextSpan>(singleLineSpan2.Content);
 
-            Assert.Equal("Content1", (singleLineSpan1.Content as MdTextSpan).Text);
-            Assert.Equal("Content2", (singleLineSpan2.Content as MdTextSpan).Text);
+            Assert.Equal("Content1", textSpan1.Text);
+            Assert.Equal("Content2", textSpan2.Text);
         }
 
         [Fact]
@@ -88,11 +88,11 @@ public void MdTableRow_can_be_initialized_with_string_content_03()
             var singleLineSpan1 = (MdSingleLineSpan)row[0];
             var singleLineSpan2 = (MdSingleLineSpan)row[1];
 
-            Assert.IsType<MdTextSpan>(singleLineSpan1.Content);
-            Assert.IsType<MdTextSpan>(singleLineSpan2.Content);
+            var textSpan1 = Assert.IsType<MdTextSpan>(singleLineSpan1.Content);
+            var textSpan2 = Assert.IsType<MdTextSpan>(singleLineSpan2.Content);
 
-            Assert.Equal("Content1", (singleLineSpan1.Content as MdTextSpan).Text);
-            Assert.Equal("Content2", (singleLineSpan2.Content as MdTextSpan).Text);
+            Assert.Equal("Content1", textSpan1.Text);
+            Assert.Equal("Content2", textSpan2.Text);
         }
 
         [Fact]

src/MarkdownGenerator.Test/_Model/_Blocks/MdTableTest.cs

@@ -86,7 +86,7 @@ public void Insert_throws_expected_exceptions()
             var instance = new MdTable(new MdTableRow(MdEmptySpan.Instance));
 
             // ACT / ASSERT
-            Assert.Throws<ArgumentNullException>(() => instance.Insert(0, null));
+            Assert.Throws<ArgumentNullException>(() => instance.Insert(0, null!));
             Assert.Throws<ArgumentOutOfRangeException>(() => instance.Insert(-1, new MdTableRow(MdEmptySpan.Instance)));
             Assert.Throws<ArgumentOutOfRangeException>(() => instance.Insert(2, new MdTableRow(MdEmptySpan.Instance)));
         }

src/MarkdownGenerator.Test/_Model/_Options/MdSerializationOptionsTest.cs

@@ -8,7 +8,7 @@ namespace Grynwald.MarkdownGenerator.Test
 {
     public class MdSerializationOptionsTest
     {
-        private object GetTestValue(Type type)
+        private object? GetTestValue(Type type)
         {
             if (!type.IsValueType)
             {
@@ -37,7 +37,7 @@ public static IEnumerable<object[]> DefaultInstancesAndProperties()
                 yield return new object[] { MdSerializationOptions.Default, property.Name };
                 foreach(var presetField in typeof(MdSerializationOptions.Presets).GetFields(BindingFlags.Static | BindingFlags.Public))
                 {
-                    yield return new object[] { presetField.GetValue(null), property.Name };
+                    yield return new object[] { presetField.GetValue(null)!, property.Name };
                 }
             }            
         }
@@ -47,16 +47,17 @@ public static IEnumerable<object[]> DefaultInstancesAndProperties()
         public void Properties_of_the_default_instances_cannot_be_modified(MdSerializationOptions instance, string propertyName)
         {
             // ARRANGE
-            var property = typeof(MdSerializationOptions).GetProperty(propertyName);
+            var property = typeof(MdSerializationOptions).GetProperty(propertyName)!;
 
             var testValue = GetTestValue(property.PropertyType);
 
             // ACT / ASSERT
-            var exception = Assert.Throws<TargetInvocationException>(() => property.SetMethod.Invoke(instance, new[] { testValue }));
-            Assert.IsType<InvalidOperationException>(exception.InnerException);
+            var exception = Assert.Throws<TargetInvocationException>(() => property.SetMethod!.Invoke(instance, new[] { testValue }));
+            Assert.NotNull(exception.InnerException);
+            var innerException = Assert.IsType<InvalidOperationException>(exception.InnerException);
 
             // exception message should indicate which property cannot be set
-            Assert.Contains(propertyName, exception.InnerException.Message);
+            Assert.Contains(propertyName, innerException.Message);
         }
 
         public static IEnumerable<object[]> Properties()
@@ -76,11 +77,11 @@ public void Properties_of_non_default_instance_can_be_modified(string propertyNa
 
             var property = typeof(MdSerializationOptions).GetProperty(propertyName);
 
-            var newValue = GetTestValue(property.PropertyType);
+            var newValue = GetTestValue(property!.PropertyType);
 
             // ACT / ASSERT
-            property.SetMethod.Invoke(instance, new[] { newValue });
-            var actualValue = property.GetMethod.Invoke(instance, Array.Empty<object>());
+            property.SetMethod!.Invoke(instance, new[] { newValue });
+            var actualValue = property.GetMethod!.Invoke(instance, Array.Empty<object>());
             Assert.Equal(newValue, actualValue);
         }
 
@@ -111,7 +112,7 @@ public static IEnumerable<object[]> PresetInstancesAndNames()
         {
             foreach (var presetField in typeof(MdSerializationOptions.Presets).GetFields(BindingFlags.Static | BindingFlags.Public))
             {
-                yield return new object[] { presetField.GetValue(null), presetField.Name };
+                yield return new object[] { presetField.GetValue(null)!, presetField.Name };
             }
         }
 

src/MarkdownGenerator.Test/_Model/_Spans/MdSpanTest.cs

@@ -18,8 +18,8 @@ public void String_can_be_implicitly_converted_to_MdSpan(string str)
             }
             else
             {
-                Assert.IsType<MdTextSpan>(span);
-                Assert.Equal(str, (span as MdTextSpan).Text);
+                var textSpan = Assert.IsType<MdTextSpan>(span);
+                Assert.Equal(str, textSpan.Text);
             }
         }
     }

src/MarkdownGenerator/Extensions/_Admonition/MdAdmonition.cs

@@ -234,7 +234,7 @@ public MdAdmonition(string type, MdSpan title, IEnumerable<MdBlock> content) : b
 
 
         /// <inheritdoc />
-        public override bool DeepEquals(MdBlock other) => other is MdAdmonition containerBlock ? DeepEquals(containerBlock) : false;
+        public override bool DeepEquals(MdBlock? other) => other is MdAdmonition containerBlock ? DeepEquals(containerBlock) : false;
 
         /// <inheritdoc />
         internal override void Accept(IBlockVisitor visitor) => visitor.Visit(this);

src/MarkdownGenerator/FactoryMethods.Blocks.cs

@@ -54,7 +54,7 @@ public static partial class FactoryMethods
         /// Creates a new instance of <see cref="MdParagraph"/> with the specified content.
         /// </summary>
         /// <param name="text">The paragraph's content</param>
-        public static MdParagraph Paragraph(MdSpan text) => new MdParagraph(text);
+        public static MdParagraph Paragraph(MdSpan text) => new MdParagraph(text!);
 
         /// <summary>
         /// Creates a new instance of <see cref="MdParagraph"/> with the specified content.
@@ -68,7 +68,7 @@ public static partial class FactoryMethods
         /// the compiler does not seem to match the method in all situations,
         /// e.g. <c>new [] { "foo", "bar" }).Select(Paragraph)</c> so this overload is still necessary.
         /// </remarks>
-        public static MdParagraph Paragraph(string text) => new MdParagraph(text);
+        public static MdParagraph Paragraph(string text) => new MdParagraph(text!);
 
         /// <summary>
         /// Creates a new instance of <see cref="MdParagraph"/> with the specified content.
@@ -170,7 +170,7 @@ public static partial class FactoryMethods
         /// the compiler does not seem to match the method in all situations,
         /// e.g. <c>new [] { "foo", "bar" }).Select(ListItem)</c> so this overload is still necessary.
         /// </remarks>
-        public static MdListItem ListItem(string content) => new MdListItem(content);
+        public static MdListItem ListItem(string content) => new MdListItem(content!);
 
         /// <summary>
         /// Creates a new instance of <see cref="MdListItem"/> containing the specified spans
@@ -233,7 +233,7 @@ public static partial class FactoryMethods
         /// the compiler does not seem to match the method in all situations,
         /// e.g. <c>new [] { "foo", "bar" }).Select(BlockQuote)</c> so this overload is still necessary.
         /// </remarks>
-        public static MdBlockQuote BlockQuote(string content) => new MdBlockQuote(content);
+        public static MdBlockQuote BlockQuote(string content) => new MdBlockQuote(content!);
 
         /// <summary>
         /// Creates a new instance of <see cref="MdBlockQuote"/> with the specified content

src/MarkdownGenerator/Internal/_DocumentSerializer/DocumentSerializer.cs

@@ -18,7 +18,7 @@ internal partial class DocumentSerializer : IBlockVisitor
         public DocumentSerializer(TextWriter writer) : this(writer, null)
         { }
 
-        public DocumentSerializer(TextWriter writer, MdSerializationOptions options)
+        public DocumentSerializer(TextWriter writer, MdSerializationOptions? options)
         {
             m_Writer = new PrefixTextWriter(writer ?? throw new ArgumentNullException(nameof(writer)));
             m_Options = options ?? MdSerializationOptions.Default;

src/MarkdownGenerator/Internal/_DocumentSerializer/_PrefixHandlers/ListPrefixHandler.cs

@@ -5,9 +5,9 @@ namespace Grynwald.MarkdownGenerator.Internal
     internal abstract class ListPrefixHandler : IPrefixHandler
     {
         protected readonly MdSerializationOptions m_SerializationOptions;
-        protected string m_ListPrefix;           // the prefix for lines other than the first line
+        protected string? m_ListPrefix;          // the prefix for lines other than the first line
         protected bool m_LineWritten = false;    // indicates if any lines have been written in the current list item
-        protected string m_ListMarker;           // the prefix for list items
+        protected string? m_ListMarker;          // the prefix for list items
 
 
         public ListPrefixHandler(MdSerializationOptions serializationOptions)
@@ -16,12 +16,12 @@ public ListPrefixHandler(MdSerializationOptions serializationOptions)
         }
 
 
-        public int PrefixLength => m_LineWritten ? m_ListPrefix.Length : m_ListMarker.Length;
+        public int PrefixLength => m_LineWritten ? m_ListPrefix!.Length : m_ListMarker!.Length;
 
 
-        public string GetBlankLinePrefix() => m_ListPrefix;
+        public string? GetBlankLinePrefix() => m_ListPrefix;
 
-        public string GetLinePrefix()
+        public string? GetLinePrefix()
         {
             // prefix the first line in the list item with the list marker,
             // other lines are just indented by the width of the list marker

src/MarkdownGenerator/Internal/_TextWriter/IPrefixHandler.cs

@@ -8,8 +8,8 @@ internal interface IPrefixHandler
         int PrefixLength { get; }
 
 
-        string GetLinePrefix();
+        string? GetLinePrefix();
 
-        string GetBlankLinePrefix();
+        string? GetBlankLinePrefix();
     }
 }

src/MarkdownGenerator/Internal/_TextWriter/PrefixTextWriter.cs

@@ -15,9 +15,9 @@ internal sealed class PrefixTextWriter
         private readonly LinkedList<IPrefixHandler> m_PrefixHandlers = new LinkedList<IPrefixHandler>();
 
 
-        public event EventHandler<EventArgs> LineWritten;
+        public event EventHandler<EventArgs>? LineWritten;
 
-        public event EventHandler<EventArgs> BlankLineRequested;
+        public event EventHandler<EventArgs>? BlankLineRequested;
 
 
         public int PrefixLength => m_PrefixHandlers.Sum(x => x.PrefixLength);

src/MarkdownGenerator/SyntaxVisualizer.cs

@@ -16,7 +16,7 @@ private class GraphBuildingVisitor : IBlockVisitor, ISpanVisitor
 
             private AsciiTreeNode CurrentNode => m_Nodes.Peek();
 
-            public AsciiTreeNode RootNode { get; private set; }
+            public AsciiTreeNode? RootNode { get; private set; }
 
 
             public void Visit(MdHeading heading)
@@ -188,7 +188,10 @@ public static string GetSyntaxTree(MdDocument document)
             document.Root.Accept(visitor);
 
             var rootNode = new AsciiTreeNode(document.GetType().Name);
-            rootNode.Children.Add(visitor.RootNode);
+            if(visitor.RootNode != null)
+            {
+                rootNode.Children.Add(visitor.RootNode);
+            }
 
             // generate ascii tree
             var treeWriter = new AsciiTreeWriter();
@@ -210,11 +213,14 @@ public static string GetSyntaxTree(MdBlock block)
 
             // convert the block into a graph
             var visitor = new GraphBuildingVisitor();
-            block.Accept(visitor);
+            block!.Accept(visitor);
 
             // generate ascii tree
             var treeWriter = new AsciiTreeWriter();
-            treeWriter.WriteNode(visitor.RootNode);
+            if (visitor.RootNode != null)
+            {
+                treeWriter.WriteNode(visitor.RootNode);
+            }
 
             // return ascii tree
             return treeWriter.ToString();