initial draft of doc-generating utility

edyoung · Sep 9, 2015 · 7e30022 · 7e30022
1 parent 09a0a7c
commit 7e30022
Show file tree

Hide file tree

Showing 7 changed files with 193 additions and 12 deletions.
diff --git a/GenerateDocs/App.config b/GenerateDocs/App.config
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<configuration>
+    <startup> 
+        <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5" />
+    </startup>
+</configuration>
diff --git a/GenerateDocs/GenerateDocs.csproj b/GenerateDocs/GenerateDocs.csproj
@@ -0,0 +1,69 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project ToolsVersion="14.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
+  <PropertyGroup>
+    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
+    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
+    <ProjectGuid>{9C82F659-178B-4B55-9268-D361718ECEAC}</ProjectGuid>
+    <OutputType>Exe</OutputType>
+    <AppDesignerFolder>Properties</AppDesignerFolder>
+    <RootNamespace>GenerateDocs</RootNamespace>
+    <AssemblyName>GenerateDocs</AssemblyName>
+    <TargetFrameworkVersion>v4.5</TargetFrameworkVersion>
+    <FileAlignment>512</FileAlignment>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
+    <PlatformTarget>AnyCPU</PlatformTarget>
+    <DebugSymbols>true</DebugSymbols>
+    <DebugType>full</DebugType>
+    <Optimize>false</Optimize>
+    <OutputPath>bin\Debug\</OutputPath>
+    <DefineConstants>DEBUG;TRACE</DefineConstants>
+    <ErrorReport>prompt</ErrorReport>
+    <WarningLevel>4</WarningLevel>
+  </PropertyGroup>
+  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
+    <PlatformTarget>AnyCPU</PlatformTarget>
+    <DebugType>pdbonly</DebugType>
+    <Optimize>true</Optimize>
+    <OutputPath>bin\Release\</OutputPath>
+    <DefineConstants>TRACE</DefineConstants>
+    <ErrorReport>prompt</ErrorReport>
+    <WarningLevel>4</WarningLevel>
+  </PropertyGroup>
+  <ItemGroup>
+    <Reference Include="System" />
+    <Reference Include="System.Core" />
+    <Reference Include="System.Xml.Linq" />
+    <Reference Include="System.Data.DataSetExtensions" />
+    <Reference Include="Microsoft.CSharp" />
+    <Reference Include="System.Data" />
+    <Reference Include="System.Net.Http" />
+    <Reference Include="System.Xml" />
+  </ItemGroup>
+  <ItemGroup>
+    <Compile Include="Program.cs" />
+    <Compile Include="Properties\AssemblyInfo.cs" />
+  </ItemGroup>
+  <ItemGroup>
+    <None Include="App.config" />
+  </ItemGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\Prequel.Tests\Prequel.Tests.csproj">
+      <Project>{ff6b7b41-e2d2-4e17-9f18-cee46cb7d3e5}</Project>
+      <Name>Prequel.Tests</Name>
+    </ProjectReference>
+    <ProjectReference Include="..\Prequel\Prequel.Library.csproj">
+      <Project>{524524fd-9882-4ce7-9208-5aef0552b6ed}</Project>
+      <Name>Prequel.Library</Name>
+    </ProjectReference>
+  </ItemGroup>
+  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
+  <!-- To modify your build process, add your task inside one of the targets below and uncomment it. 
+       Other similar extension points exist, see Microsoft.Common.targets.
+  <Target Name="BeforeBuild">
+  </Target>
+  <Target Name="AfterBuild">
+  </Target>
+  -->
+</Project>
diff --git a/GenerateDocs/Program.cs b/GenerateDocs/Program.cs
@@ -0,0 +1,31 @@
+using Prequel;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text;
+using System.Threading.Tasks;
+
+namespace GenerateDocs
+{
+    /// <summary>
+    /// Output markdown text for info about the program's options, to keep docs in sync with code
+    /// </summary>
+    class Program
+    {
+        static void Main(string[] args)
+        {
+            for (int id = WarningInfo.MinWarningID; id <= WarningInfo.MaxWarningID; id++)
+            {
+                WarningID warningID = (WarningID)id;
+                WarningInfo info = Warning.WarningTypes[warningID];
+
+                Console.WriteLine(@"
+### Warning {0} : {1}
+{2}
+
+{3}
+", (int)info.ID, info.Name, info.Level, info.Description);
+            }
+        }
+    }
+}
diff --git a/GenerateDocs/Properties/AssemblyInfo.cs b/GenerateDocs/Properties/AssemblyInfo.cs
@@ -0,0 +1,36 @@
+using System.Reflection;
+using System.Runtime.CompilerServices;
+using System.Runtime.InteropServices;
+
+// General Information about an assembly is controlled through the following 
+// set of attributes. Change these attribute values to modify the information
+// associated with an assembly.
+[assembly: AssemblyTitle("GenerateDocs")]
+[assembly: AssemblyDescription("")]
+[assembly: AssemblyConfiguration("")]
+[assembly: AssemblyCompany("")]
+[assembly: AssemblyProduct("GenerateDocs")]
+[assembly: AssemblyCopyright("Copyright ©  2015")]
+[assembly: AssemblyTrademark("")]
+[assembly: AssemblyCulture("")]
+
+// Setting ComVisible to false makes the types in this assembly not visible 
+// to COM components.  If you need to access a type in this assembly from 
+// COM, set the ComVisible attribute to true on that type.
+[assembly: ComVisible(false)]
+
+// The following GUID is for the ID of the typelib if this project is exposed to COM
+[assembly: Guid("9c82f659-178b-4b55-9268-d361718eceac")]
+
+// Version information for an assembly consists of the following four values:
+//
+//      Major Version
+//      Minor Version 
+//      Build Number
+//      Revision
+//
+// You can specify all the values or you can default the Build and Revision Numbers 
+// by using the '*' as shown below:
+// [assembly: AssemblyVersion("1.0.*")]
+[assembly: AssemblyVersion("1.0.0.0")]
+[assembly: AssemblyFileVersion("1.0.0.0")]
diff --git a/Prequel.Tests/WarningTests.cs b/Prequel.Tests/WarningTests.cs
@@ -15,12 +15,15 @@ public class WarningTests
         /// </summary>
         [Fact]
         public void AllWarningsInMap()
-        {
-            for (int id = (int)WarningID.Min; id < (int)WarningID.Max ; id++)
+        {            
+            for (int id = WarningInfo.MinWarningID; id <= WarningInfo.MaxWarningID ; id++)
             {
                 WarningID warningID = (WarningID)id;
-                Assert.Equal(warningID, Warning.WarningTypes[warningID].ID); 
+                Assert.Equal(warningID, Warning.WarningTypes[warningID].ID); // make sure every warning is in the map and has correct id
             }
+
+            // make sure min and max are up-to-date
+            Assert.Equal(Warning.WarningTypes.Count, (WarningInfo.MaxWarningID - WarningInfo.MinWarningID) + 1);
         }
     }
 }
diff --git a/Prequel.sln b/Prequel.sln
@@ -9,6 +9,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Prequel.Tests", "Prequel.Te
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Prequel.exe", "Prequel.exe\Prequel.exe.csproj", "{2343C1AC-134F-400A-9B3C-9ED44EBA8273}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GenerateDocs", "GenerateDocs\GenerateDocs.csproj", "{9C82F659-178B-4B55-9268-D361718ECEAC}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -27,6 +29,10 @@ Global
 		{2343C1AC-134F-400A-9B3C-9ED44EBA8273}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{2343C1AC-134F-400A-9B3C-9ED44EBA8273}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{2343C1AC-134F-400A-9B3C-9ED44EBA8273}.Release|Any CPU.Build.0 = Release|Any CPU
+		{9C82F659-178B-4B55-9268-D361718ECEAC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{9C82F659-178B-4B55-9268-D361718ECEAC}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{9C82F659-178B-4B55-9268-D361718ECEAC}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{9C82F659-178B-4B55-9268-D361718ECEAC}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

diff --git a/Prequel/Warning.cs b/Prequel/Warning.cs
@@ -8,14 +8,12 @@ namespace Prequel
 {
     public enum WarningID
     {
-        Min = UndeclaredVariableUsed,
         UndeclaredVariableUsed = 1,
         UnusedVariableDeclared,
         ProcedureWithoutNoCount,
-        ProcedureWithSPPrefix,
-        Max = ProcedureWithSPPrefix
+        ProcedureWithSPPrefix,        
     }
-
+    
     public enum WarningLevel
     {
         None = 0,
@@ -27,6 +25,9 @@ public enum WarningLevel
 
     public class WarningInfo
     {
+        public const int MinWarningID = (int)WarningID.UndeclaredVariableUsed;
+        public const int MaxWarningID = (int)WarningID.ProcedureWithSPPrefix;
+
         public WarningLevel Level
         {
             get; private set;
@@ -37,10 +38,22 @@ public WarningID ID
             get; private set;
         }
 
-        public WarningInfo(WarningID id, WarningLevel level)
+        public string Name
+        {
+            get; private set;
+        }
+
+        public string Description
+        {
+            get; private set;
+        }
+
+        public WarningInfo(WarningID id, WarningLevel level, string name, string description)
         {
             ID = id;
             Level = level;
+            Name = name;
+            Description = description;
         }
     }
 
@@ -64,10 +77,27 @@ public Warning(int line, WarningID number, string message)
         private static IDictionary<WarningID, WarningInfo> InitWarningLevelMap()
         {
             IDictionary<WarningID, WarningInfo> warningInfo = new Dictionary<WarningID, WarningInfo>();
-            warningInfo[WarningID.UndeclaredVariableUsed] = new WarningInfo(WarningID.UndeclaredVariableUsed, WarningLevel.Critical);
-            warningInfo[WarningID.UnusedVariableDeclared] = new WarningInfo(WarningID.UnusedVariableDeclared, WarningLevel.Minor);
-            warningInfo[WarningID.ProcedureWithoutNoCount] = new WarningInfo(WarningID.ProcedureWithoutNoCount, WarningLevel.Minor);
-            warningInfo[WarningID.ProcedureWithSPPrefix] = new WarningInfo(WarningID.ProcedureWithSPPrefix, WarningLevel.Serious);
+            warningInfo[WarningID.UndeclaredVariableUsed] = new WarningInfo(
+                WarningID.UndeclaredVariableUsed, 
+                WarningLevel.Critical,
+                "Undeclared Variable used",
+                "A variable which was not declared was referenced or set. Declare it before use, for example 'DECLARE @variable AS INT'");
+            warningInfo[WarningID.UnusedVariableDeclared] = new WarningInfo(
+                WarningID.UnusedVariableDeclared, 
+                WarningLevel.Minor,
+                "Unused Variable declared",
+                "A variable or parameter was declared, but never referenced. It could be removed without affecting the procedure's logic, or this could indicate a typo or logical error");
+            warningInfo[WarningID.ProcedureWithoutNoCount] = new WarningInfo(
+                WarningID.ProcedureWithoutNoCount, 
+                WarningLevel.Minor,
+                "Procedure without SET NOCOUNT ON",
+                @"Performance for stored procedures can be increased with the SET NOCOUNT ON option. The difference can range from tiny to substantial depending on the nature of the sproc. 
+Some SQL tools require the rowcount to be returned - if you use one of those, suppress this warning.");
+            warningInfo[WarningID.ProcedureWithSPPrefix] = new WarningInfo(
+                WarningID.ProcedureWithSPPrefix, 
+                WarningLevel.Serious,
+                "Procedure name begins with sp_",
+                "sp_ is a reserved prefix in SQL server. Even a sproc which does not clash with any system procedure incurs a performance penalty when using this prefix. Rename the procedure");
             return warningInfo;
         }
     }