barry-jones / live-documenter Goto Github PK

When a return type is a generic type e.g. List the return type shows simply as List<>.

Perhaps the following would be better:

public List<ContentEntry> GetParents();

Would show in the documentation as:

Returns
ContentEntry - Details of return value

Migrate all projects (except Desktop application and PE Viewer) to netstandard 2.0 libraries and net core 2.2. To enable the use of the API (and future web applications and projects) to run on other platforms.

The DocumentTest library AllOutputTypesClass contains a method:

public string[][] JaggedReturnArray(string[][] jaggy)

This is causing a null reference exception when veiwing documentation.

System.NullReferenceException
  HResult=0x80004003
  Message=Object reference not set to an instance of an object.
  Source=Live Documenter
  StackTrace:
   at TheBoxSoftware.DeveloperSuite.LiveDocumenter.Pages.MethodPage.CreateEntryKey(TypeRef typeReference) in D:\Projects\live-documenter\Source\TheBoxSoftware.DeveloperSuite.LiveDocumenter\Pages\MethodPage.cs:line 173

Currently only C# for example is output in the syntax blocks. The XML container syntaxblocks will support multiple entries.

This will also require an update to the exporter XSLTs to ensure they all still work and to make sure the outputted content is styled nicely.

For the moment methods and properties do not include links to return value types.

Example (method)

• Assembly LibGit2Sharp
• Class LibGit2Sharp.Repository
• Method CherryPick(Commit, Signature, CherryPickOptions)

The help conveniently provides links to the parameter types Commit,
Signature, CherryPickOptions but the return value type
CherryPickResult is missing the link to its help page.

Example (property)

• Assembly LibGit2Sharp
• Class LibGit2Sharp.Repository
• Property Branches

The help page does not have a link for the return value type BranchCollection.

Given the following defenition:

public readonly static SyntaxToken Space = new SyntaxToken(" ", SyntaxTokens.Text);

Is displayed in the syntax field as:

public SyntaxToken Space;

The constants information needs to be read from the signature.

Saxon HE is used because of its XPATH 2.0 and XSLT 2.0 implementations which is unavailable in .NET core. However Saxon HE does not have a .NET core version and as such this application still relies on the .NET Framework to function correctly.

This dependancy needs to be replaced by a .net core xslt processor.

Since net core is cross platform and this seems to be where MS is heading with .NET. A cross platform user interface will be needed. Currently there is no cross platform .net gui available and while WPF support will be added in version 3 this will still be windows only.

The only solution I can see is to use electron over an aspnet core web api. This will give the ability for creating a nice slick user interface. Though could be a little slow as electron will have to spawn an aspnet core application running a kestrel server underneath.

Other concerns are going to be around how to manage the files, ldproj files, opening solutions library and projects, watching for file changes to keep the documentation up to date and exporting the content.

• Create a proof of concept application

This is not handled correctly in the rendered XML:

<entry id="4294967518" subId="" type="properties" visibility="public" cref="P:TheBoxSoftware.API.LiveDocumenter.TableOfContents.Item(System.Int32)">
    <name>Item()</name>
    <summary>
        <text>Gets the ContentEntry at the specified index. </text>
    </summary>
</entry>

Or in the live documenter interface:

Look at how a json export could be accomplished to enable websites to ingest the documentation as a data source (much like XSLT over XML without the processing).

The documentationtest.dll has the following method DocumentationTest.AllOutputTypesClass.JaggedReturnArray which returns a:

string[][]

This currently fails when attempting to get the display name of the return type as only the first level is checked on Array types see MethodDef.GetReturnType().

After the export has completed in live documenter, you only have the option to finish.

Maybe it would be a good idea to link to the exported content.

Sandcastle supports things like <see href="https://example.com">title</see>, <see langword="null" />

http://ewsoftware.github.io/XMLCommentsGuide/html/983fed56-321c-4daf-af16-e3169b28ffcd.htm

The command line application shows the message NameCriterion regexString(^([^\.]+|.*\.[^\\\.]*)$) in the export output. This is not expected and should be removed, or if it is an issue with content, should show as a warning or error.

When a constructor has parameters, th C# syntax does not indent the parameters like it does on methods.

public EventDef(
string name,
AssemblyDef definingAssembly,
TypeDef containingType
)

As appose to a method formatting:

public TypeDef FindType(
	string theNamespace,
	string theTypeName
	)

Allow overriding/replacing of exported documentation in the target directory from both the UI and CLI tool.

Was pointing to the old livedocumenter.com website and needs to point to the new documentation site.

http://livedocumenter.barryjones.me.uk/docs/issues/no-xml-comments/

MSDN allows you to view documentation for the same type/library for a particular version. Implement something similar

Api that allows the searching and returning of documentation, this would enable users to pull the data in to exsiting websites.

After #23 is resolved. All the exporters will need to be udpated to show the return details and type inforamation for methods.

It only displays the type for the array not the fact it is an array of type.

String

Instead of:

string[][]

Currently tupes are not displayed in their C# syntax naturally e.g.

public (string, string) ReturnedSomeStrings()

But as the underlying type

public ValueTuple<string, string> ReturnedSomeStrings()

Remove BoxSoftware from namespaces, screens and application information files.

The web export LDEC file was developed a long time ago the the styling and structure of the HTML needs to be updated to HTML 5 with a modern style.

Details of how LDEC files work is available at http://livedocumenter.barryjones.me.uk/export/create-own-ldec-file/.

The source code for LDEC files is located in /Source/TheBoxSoftware.DeveloperSuite.LiveDocumenter/ApplicationData/

Provide better feedback in the exporter command line application. Currently this is the wrong kind of feedback as it shows the internal workings of the export and not overall progress. E.g.

Live Documenter Exporter Version: 2.1.4-alpha+cec2825480

Details:
  Visible members: (Public|Protected|Internal|InternalProtected|Private)
  theboxsoftware.reflection.dll contains 3045 members and types.

Exporting with web-msdn.ldec to location c:\temp\web\.
The export began at 09/01/2019 16:51:20.
Export started
  Export as XML...
  Saving output files...
  Transforming XML...
  Cleaning up
The export completed at 09/01/2019 16:52:11, taking 00:00:50.5864218.

Perhaps a progress bar (or other indicator could be used e.g.)

Live Documenter Exporter Version: 2.1.4-alpha+cec2825480

Details:
  Visible members: (Public|Protected|Internal|InternalProtected|Private)
  theboxsoftware.reflection.dll contains 3045 members and types.

Exporting with web-msdn.ldec to location c:\temp\web\.
The export began at 09/01/2019 16:51:20.
[oooooo    ]
The export completed at 09/01/2019 16:52:11, taking 00:00:12.5864218.

Given the following code:

public ref Person GetContactInformation(string fname, string lname)
{
    // ...method implementation...
    return ref p;
}

The ref modifier is not displayed in the syntax, though it has been correctly read from the return type signature.

Barry, Firstly thank you. I stumbled across your tool this morning and I must say "It's frigging awesome"
I have used other documentation tools in the past and well in just a few hours, I've set up your exporter on my DevOps build pipeline and have the documents published to an intranet site. (Very impressive). However, I have some questions.

• Your SSL looks like it may have expired, you might want to check that out.

• Sadly when I point to my .sln file in the configuration It fails to pick up anything.
  I added my output.dll in the configuration/document tag which generates the documentation so as a workaround can you have multiple documents?

• How can I get the output to overwrite the existing files?

The xml produced for exporting methods does not contain the details and description of the return types. This needs to be processed and output as part of the rendered xml to make it available to the ldec exporter.

Improve ui to a more up to date appearance and improve readability of documentation.

The get; text is provided correctly but set; is no being showed.

Example is viewing theboxsoftware.reflection.dll library in live documenter.

StringStream
      Gets or sets a reference to the string stream. 
Syntax
public IStringStream StringStream {
	get;
	 ;
	}
Remarks
This has been created to reduce the cost of obtaining this information, it is a well access field and storing it behind a property just increases cost for no reason. 

Current implementation expects AssemblyName, OutputType and conditional property groups as per the 2005 project file implementation.

This needs to be updated to correctly read and understand the new project file format and its default output directories.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <PropertyGroup>
    <GenerateAssemblyInfo>false</GenerateAssemblyInfo>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <DocumentationFile>bin\Debug\netstandard2.0\TheBoxSoftware.xml</DocumentationFile>
  </PropertyGroup>

</Project>

Old style 2005 format

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup>
    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
    <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
    <ProductVersion>9.0.30729</ProductVersion>
    <SchemaVersion>2.0</SchemaVersion>
    <ProjectGuid>{20B33F17-25DF-4DB1-AC52-A8128AF0CDD1}</ProjectGuid>
    <OutputType>Library</OutputType>
    <AppDesignerFolder>Properties</AppDesignerFolder>
    <RootNamespace>TheBoxSoftware</RootNamespace>
    <AssemblyName>TheBoxSoftware</AssemblyName>
    <TargetFrameworkVersion>v4.7.2</TargetFrameworkVersion>
    <FileAlignment>512</FileAlignment>
    <SccProjectName>Svn</SccProjectName>
    <SccLocalPath>Svn</SccLocalPath>
    <SccAuxPath>Svn</SccAuxPath>
    <SccProvider>SubversionScc</SccProvider>
    <FileUpgradeFlags>
    </FileUpgradeFlags>
    <OldToolsVersion>3.5</OldToolsVersion>
    <UpgradeBackupLocation />
    <PublishUrl>http://localhost/TheBoxSoftware/</PublishUrl>
    <Install>true</Install>
    <InstallFrom>Web</InstallFrom>
    <UpdateEnabled>true</UpdateEnabled>
    <UpdateMode>Foreground</UpdateMode>
    <UpdateInterval>7</UpdateInterval>
    <UpdateIntervalUnits>Days</UpdateIntervalUnits>
    <UpdatePeriodically>false</UpdatePeriodically>
    <UpdateRequired>false</UpdateRequired>
    <MapFileExtensions>true</MapFileExtensions>
    <ApplicationRevision>0</ApplicationRevision>
    <ApplicationVersion>1.0.0.%2a</ApplicationVersion>
    <IsWebBootstrapper>true</IsWebBootstrapper>
    <UseApplicationTrust>false</UseApplicationTrust>
    <BootstrapperEnabled>true</BootstrapperEnabled>
    <TargetFrameworkProfile />
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
    <DebugSymbols>true</DebugSymbols>
    <DebugType>full</DebugType>
    <Optimize>false</Optimize>
    <OutputPath>bin\Debug\</OutputPath>
    <DefineConstants>DEBUG;TRACE</DefineConstants>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
    <CodeAnalysisRuleSet>AllRules.ruleset</CodeAnalysisRuleSet>
    <DocumentationFile>bin\Debug\TheBoxSoftware.XML</DocumentationFile>
    <Prefer32Bit>false</Prefer32Bit>
  </PropertyGroup>
  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
    <DebugType>pdbonly</DebugType>
    <Optimize>true</Optimize>
    <OutputPath>bin\Release\</OutputPath>
    <DefineConstants>TRACE</DefineConstants>
    <ErrorReport>prompt</ErrorReport>
    <WarningLevel>4</WarningLevel>
    <CodeAnalysisRuleSet>AllRules.ruleset</CodeAnalysisRuleSet>
    <Prefer32Bit>false</Prefer32Bit>
  </PropertyGroup>
  <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Test|AnyCPU'">
    <DebugSymbols>true</DebugSymbols>
    <OutputPath>bin\Test\</OutputPath>
    <DefineConstants>TRACE;DEBUG;TEST</DefineConstants>
    <DocumentationFile>bin\Debug\TheBoxSoftware.XML</DocumentationFile>
    <DebugType>full</DebugType>
    <PlatformTarget>AnyCPU</PlatformTarget>
    <ErrorReport>prompt</ErrorReport>
    <CodeAnalysisRuleSet>AllRules.ruleset</CodeAnalysisRuleSet>
    <Prefer32Bit>false</Prefer32Bit>
  </PropertyGroup>
  <ItemGroup>
    <Reference Include="System" />
    <Reference Include="System.Core">
      <RequiredTargetFramework>3.5</RequiredTargetFramework>
    </Reference>
    <Reference Include="System.Xml.Linq">
      <RequiredTargetFramework>3.5</RequiredTargetFramework>
    </Reference>
    <Reference Include="System.Data.DataSetExtensions">
      <RequiredTargetFramework>3.5</RequiredTargetFramework>
    </Reference>
    <Reference Include="System.Data" />
    <Reference Include="System.Xml" />
  </ItemGroup>
  <ItemGroup>
    <Compile Include="..\Solution Items\LibraryVersionInfo.cs">
      <Link>LibraryVersionInfo.cs</Link>
    </Compile>
    <Compile Include="Diagnostics\Logging.cs" />
    <Compile Include="Diagnostics\TraceHelper.cs" />
    <Compile Include="IExtendedException.cs" />
    <Compile Include="IFileSystem.cs" />
    <Compile Include="Properties\AssemblyInfo.cs" />
  </ItemGroup>
  <ItemGroup>
    <BootstrapperPackage Include="Microsoft.Net.Client.3.5">
      <Visible>False</Visible>
      <ProductName>.NET Framework 3.5 SP1 Client Profile</ProductName>
      <Install>false</Install>
    </BootstrapperPackage>
    <BootstrapperPackage Include="Microsoft.Net.Framework.3.5.SP1">
      <Visible>False</Visible>
      <ProductName>.NET Framework 3.5 SP1</ProductName>
      <Install>true</Install>
    </BootstrapperPackage>
    <BootstrapperPackage Include="Microsoft.Windows.Installer.3.1">
      <Visible>False</Visible>
      <ProductName>Windows Installer 3.1</ProductName>
      <Install>true</Install>
    </BootstrapperPackage>
  </ItemGroup>
  <ItemGroup>
    <None Include="documentation\validationinfo.xml" />
  </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>

Previously error reporting sent details back to a box software server. This is no longer available. Error reporting still provides option though no functionality exists.

This needs to be changed to either, give detail and point them to GitHub issues or to allow them to send to a diffent end point or via email the details of the issue.

Implementation (perhaps using exsiting API) or a website that provides wiki style documentation with ability to import automatically generated content from documented APIs.

The HTML Help executables are used to compile the compiled html help files. These are only available on windows and when searching for the install directory the fallback search looks through the registry.

So as part of the move to the .NET core the compatabilty pack has been used. This will not work on non-windows platforms so needs some action to remove or not have these dependancies on other platforms.

In the live documenter application and in the export XML. The value element from teh xml comments is not used and the type of the property, field etc is also not output/displayed.

This is visible in the documentationtest.dll library, search for OutParameter.

Currently, very little information is provided from the console application. This should be increased to include all details currently in verbose mode. Verbose should include a lot more detail or be removed.

The current default output looks like this:

Exporting with web-msdn.ldec to location c:\temp\web\.
  NameCriterion regexString(^([^\.]+|.*\.[^\\\.]*)$)

Exporting with htmlhelp1-msdn.ldec to location c:\temp\htmlhelp-1\.
  NameCriterion regexString(^([^\.]+|.*\.[^\\\.]*)$)

Exporting with htmlhelp2-msdn.ldec to location c:\temp\htmlhelp-2\.
[err] Could not locate the HTML Help 2.0 compiler 'hxcomp.exe'. Please check it is installed correctly.

Exporting with helpviewer1-msdn.ldec to location c:\temp\helpviewer-1\.
  NameCriterion regexString(^([^\.]+|.*\.[^\\\.]*)$)

Exporting with xml.ldec to location c:\temp\xml\.

Versus the verbose output, which updates user that stuff is happening and and at what point in the process it is.

Live Documenter Exporter Version: 2.0.4.0

Details:
  Visible members: (Public|Protected|Internal|InternalProtected|Private)
  theboxsoftware.reflection.dll contains 2443 members and types.

Exporting with web-msdn.ldec to location c:\temp\web\.
The export began at 06/01/2019 15:57:19.
Export started
  Export as XML...
  Saving output files...
  NameCriterion regexString(^([^\.]+|.*\.[^\\\.]*)$)
  Transforming XML...
  Cleaning up
The export completed at 06/01/2019 15:57:41, taking 00:00:21.4907696.

Exporting with htmlhelp1-msdn.ldec to location c:\temp\htmlhelp-1\.
The export began at 06/01/2019 15:57:41.
Export started
  Export as XML...
  Saving output files...
  NameCriterion regexString(^([^\.]+|.*\.[^\\\.]*)$)
  Transforming XML...
  Compiling help...
  Publishing help...
  Cleaning up
The export completed at 06/01/2019 15:58:04, taking 00:00:23.0854660.

Exporting with htmlhelp2-msdn.ldec to location c:\temp\htmlhelp-2\.
[err] Could not locate the HTML Help 2.0 compiler 'hxcomp.exe'. Please check it is installed correctly.

Exporting with helpviewer1-msdn.ldec to location c:\temp\helpviewer-1\.
The export began at 06/01/2019 15:58:04.
Export started
  Export as XML...
  Saving output files...
  NameCriterion regexString(^([^\.]+|.*\.[^\\\.]*)$)
  Transforming XML...
  Compiling help...
  Publishing help...
  Cleaning up
The export completed at 06/01/2019 15:58:28, taking 00:00:24.7607731.

Exporting with xml.ldec to location c:\temp\xml\.
The export began at 06/01/2019 15:58:28.
Export started
  Export as XML...
  Saving output files...
  Publishing XML files...
  Cleaning up
The export completed at 06/01/2019 15:58:43, taking 00:00:14.2420005.

Currently the console application uses a configuration xml file to describe how the some documentation will be exported. It details which files and members will be exported, and what exporters to use. We should allow this with options on the console application to simplify the application and get people up and running without needing to teach the ins and outs of this file.

    -h                    show help information
    -v                    show verbose export details
    <filename>  The path to the configuration xml file, library, project or solution
    -format [xml|web|htmlhelp1|htmlhelp2|helpviewer] 
                           The type of export formatter to use. Defaults to web.
    -to                  Directory to export to. Defaults to current directory
    -filters[public|protected|internal|internalprotected|private] 
                          Filters for visibility of members to export. Defaults to public.

Check all of the XSLT for the exporters and see how difficult it is to have the same functionality but only using XSLT 1.0.

Normally a members fields, properties, methods etc are stored as an entry under an entries element with details of the id, type naem and cref etc e.g.

<entries>
    <entry id="4294969814" subId="" type="constructor" visibility="protected" cref="M:TheBoxSoftware.Reflection.Signatures.SignatureConvertor.#ctor">
        <name>SignatureConvertor()</name>
    </entry>
</entries>

Enumerations are handled as values.

<values>
    <value>
        <name>MethodDef</name>
        <description>
            <summary>
                <text>Signiture which describes the signiture or of a method or global function. </text>
            </summary>
        </description>
    </value>
</values>

Consider converting the same format as all of the others to simplify XSLT processing.

Markdown as a documentation source is used often in development and can also be used to create websites (ala Jekyll and GitHub pages). Look in to the prospect of exporting direct to markdown.

This functionality could be created curently using XSLT in a LDEC file which would provide more configurability.

Need to update pipeline and release configurations to make sure xml comment files are exporterd with published content.

Add exporting and viewing of the F# language syntax for code snippets.