private static bool NeedsComment(DocumentationSettings documentationSettings, SyntaxKind syntaxKind, SyntaxKind parentSyntaxKind, Accessibility declaredAccessibility, Accessibility effectiveAccessibility)
{
if (documentationSettings.DocumentInterfaces &&
(syntaxKind == SyntaxKind.InterfaceDeclaration || parentSyntaxKind == SyntaxKind.InterfaceDeclaration))
{
// DocumentInterfaces => all interfaces must be documented
return(true);
}
if (documentationSettings.DocumentPrivateElements)
{
// DocumentPrivateMembers => everything except declared private fields must be documented
return(true);
}
switch (effectiveAccessibility)
{
case Accessibility.Public:
case Accessibility.Protected:
case Accessibility.ProtectedOrInternal:
// These items are part of the exposed API surface => document if configured
return(documentationSettings.DocumentExposedElements);
case Accessibility.ProtectedAndInternal:
case Accessibility.Internal:
// These items are part of the internal API surface => document if configured
return(documentationSettings.DocumentInternalElements);
case Accessibility.NotApplicable:
case Accessibility.Private:
default:
return(false);
}
}
private static void CheckCompanyName(SyntaxTreeAnalysisContext context, DocumentationSettings documentationSettings, Compilation compilation, XmlFileHeader fileHeader, XElement copyrightElement)
{
var companyName = copyrightElement.Attribute("company")?.Value;
if (string.IsNullOrWhiteSpace(companyName))
{
var location = fileHeader.GetElementLocation(context.Tree, copyrightElement);
context.ReportDiagnostic(Diagnostic.Create(SA1640Descriptor, location));
return;
}
if (compilation.IsAnalyzerSuppressed(SA1641Descriptor))
{
return;
}
if (string.Equals(documentationSettings.CompanyName, DocumentationSettings.DefaultCompanyName, StringComparison.OrdinalIgnoreCase))
{
// The company name is meaningless until configured by the user.
return;
}
if (string.CompareOrdinal(companyName, documentationSettings.CompanyName) != 0)
{
var location = fileHeader.GetElementLocation(context.Tree, copyrightElement);
context.ReportDiagnostic(Diagnostic.Create(SA1641Descriptor, location));
}
}
private static bool CompareCopyrightText(DocumentationSettings documentationSettings, string copyrightText)
{
// make sure that both \n and \r\n are accepted from the settings.
var reformattedCopyrightTextParts = documentationSettings.CopyrightText.Replace("\r\n", "\n").Split('\n');
var fileHeaderCopyrightTextParts = copyrightText.Replace("\r\n", "\n").Split('\n');
if (reformattedCopyrightTextParts.Length != fileHeaderCopyrightTextParts.Length)
{
return(false);
}
// compare line by line, ignoring leading and trailing whitespace on each line.
for (var i = 0; i < reformattedCopyrightTextParts.Length; i++)
{
if (string.CompareOrdinal(reformattedCopyrightTextParts[i].Trim(), fileHeaderCopyrightTextParts[i].Trim()) != 0)
{
return(false);
}
}
return(true);
}
private static void CheckCopyrightText(SyntaxTreeAnalysisContext context, DocumentationSettings documentationSettings, Compilation compilation, XmlFileHeader fileHeader, XElement copyrightElement)
{
var copyrightText = copyrightElement.Value;
if (string.IsNullOrWhiteSpace(copyrightText))
{
var location = fileHeader.GetElementLocation(context.Tree, copyrightElement);
context.ReportDiagnostic(Diagnostic.Create(SA1635Descriptor, location));
return;
}
if (compilation.IsAnalyzerSuppressed(SA1636Descriptor))
{
return;
}
string fileName = Path.GetFileName(context.Tree.FilePath);
var settingsCopyrightText = documentationSettings.GetCopyrightText(fileName);
if (string.Equals(settingsCopyrightText, DocumentationSettings.DefaultCopyrightText, StringComparison.OrdinalIgnoreCase))
{
// The copyright text is meaningless until the company name is configured by the user.
return;
}
// trim any leading / trailing new line or whitespace characters (those are a result of the XML formatting)
if (!CompareCopyrightText(context, documentationSettings, copyrightText.Trim('\r', '\n', ' ', '\t')))
{
var location = fileHeader.GetElementLocation(context.Tree, copyrightElement);
context.ReportDiagnostic(Diagnostic.Create(SA1636Descriptor, location));
}
}
private static void CheckCopyrightHeader(SyntaxTreeAnalysisContext context, DocumentationSettings documentationSettings, Compilation compilation, XmlFileHeader fileHeader)
{
var copyrightElement = fileHeader.GetElement("copyright");
if (copyrightElement == null)
{
context.ReportDiagnostic(Diagnostic.Create(SA1634Descriptor, fileHeader.GetLocation(context.Tree)));
return;
}
if (!compilation.IsAnalyzerSuppressed(SA1637Descriptor))
{
CheckFile(context, compilation, fileHeader, copyrightElement);
}
if (!compilation.IsAnalyzerSuppressed(SA1640Descriptor))
{
CheckCompanyName(context, documentationSettings, compilation, fileHeader, copyrightElement);
}
if (!compilation.IsAnalyzerSuppressed(SA1635Descriptor))
{
CheckCopyrightText(context, documentationSettings, compilation, fileHeader, copyrightElement);
}
}
public Analyzer(AnalyzerOptions options)
{
StyleCopSettings settings = options.GetStyleCopSettings();
this.documentationSettings = settings.DocumentationRules;
}
public Analyzer(AnalyzerOptions options)
{
StyleCopSettings settings = options.GetStyleCopSettings();
this.documentationSettings = settings.DocumentationRules;
}
public static bool NeedsComment(DocumentationSettings documentationSettings, SyntaxKind syntaxKind, SyntaxKind parentSyntaxKind, Accessibility declaredAccessibility, Accessibility effectiveAccessibility)
{
if (documentationSettings.DocumentInterfaces
&& (syntaxKind == SyntaxKind.InterfaceDeclaration || parentSyntaxKind == SyntaxKind.InterfaceDeclaration))
{
// DocumentInterfaces => all interfaces must be documented
return true;
}
if (syntaxKind == SyntaxKind.FieldDeclaration && documentationSettings.DocumentPrivateFields)
{
// DocumentPrivateFields => all fields must be documented
return true;
}
if (documentationSettings.DocumentPrivateElements)
{
if (syntaxKind == SyntaxKind.FieldDeclaration && declaredAccessibility == Accessibility.Private)
{
// Handled by DocumentPrivateFields
return false;
}
// DocumentPrivateMembers => everything except declared private fields must be documented
return true;
}
switch (effectiveAccessibility)
{
case Accessibility.Public:
case Accessibility.Protected:
case Accessibility.ProtectedOrInternal:
// These items are part of the exposed API surface => document if configured
return documentationSettings.DocumentExposedElements;
case Accessibility.ProtectedAndInternal:
case Accessibility.Internal:
// These items are part of the internal API surface => document if configured
return documentationSettings.DocumentInternalElements;
case Accessibility.NotApplicable:
case Accessibility.Private:
default:
return false;
}
}
private static int Main(string[] args)
{
try
{
var configFile = new FileInfo(Path.Combine(Environment.CurrentDirectory,
"config.ini"));
var ini = new IniFileConfigRepository(configFile);
foreach (var settings in DocumentationSettings.FromConfig(ini)
.Where(ds => ds.IsActive))
{
try
{
var site = new Site(settings.WikiUrl,
settings.Username, settings.Password.ToUnsecureString());
var doc = AssemblyDocumentation.FromFile(new FileInfo(settings.AssemblyFile));
doc.UpdateSettings(settings);
var asmPageName = doc.GetWikiPageName();
var asmPage = new Page(site, asmPageName);
asmPage.LoadWithMetadata();
asmPage.ResolveRedirect();
asmPage.text = doc.ToMediaWiki();
asmPage.Save();
}
catch (Exception ex)
{
GlobalConsole.Current
.InvokeForConsoleColor((c, state) => c.WriteLine(state.Exception),
new
{
Exception = ex.GetBaseException() ?? ex,
}, foreColor: ConsoleColor.Red
, bgColor: ConsoleColor.Black);
}
}
return(0);
}
catch (Exception ex)
{
GlobalConsole.Current
.InvokeForConsoleColor((c, state) => c.WriteLine(state.Exception),
new
{
Exception = ex.GetBaseException() ?? ex,
}, foreColor: ConsoleColor.Yellow
, bgColor: ConsoleColor.Red);
return(1);
}
finally
{
#if DEBUG
global::MarcelJoachimKloubert.CLRToolbox.IO.GlobalConsole.Current.WriteLine();
global::MarcelJoachimKloubert.CLRToolbox.IO.GlobalConsole.Current.WriteLine();
global::MarcelJoachimKloubert.CLRToolbox.IO.GlobalConsole.Current.WriteLine("===== ENTER ====");
global::MarcelJoachimKloubert.CLRToolbox.IO.GlobalConsole.Current.ReadLine();
#endif
}
}
