How-to documentation

[jhoek]

How about using Xamarin Workbooks or another type of "active" documents?

[jhoek]

howto.ps1:

$DemoPath = Join-Path -Path $PSScriptRoot -ChildPath .\CBreeze\UncommonSense.CBreeze.Demo

Get-ChildItem -Path $DemoPath -Filter *.cs |
    Where-Object Name -ne Program.cs |
    ForEach-Object { 
        $FileName = $_.FullName

        Get-Content -Path $FileName |
        Where-Object { $_ -notmatch '^using' } |
        Where-Object { $_ -notmatch '^namespace' } |
        Where-Object { $_ -notmatch '^\s*\{' } | 
        Foreach-Object { if ($_ -match '^\s{8}}') { '```' } else { $_} } |
        Where-Object { $_ -notmatch '^\s*}' } | 
        Where-Object { $_ -notmatch '^\s*public static class' } | 
        ForEach-Object { if ($_ -match '^\s*public static void') { '```c#' } else { $_ } } |
        ForEach-Object { $_ -replace '^\s*//', '' } | 
        Set-Content -Path ($FileName + '.md')
    }

with this demo:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using UncommonSense.CBreeze.Core;
using UncommonSense.CBreeze.Read;

namespace UncommonSense.CBreeze.Demo
{
    // # Basic operations
    public static class Basic
    {
        // ## Creating a new application
        public static void _00100CreatingAnApplication()
        {
            var application = new Application();
        }

        // ## Initializing an application with objects
        public static void _00200InitializingAnApplicationWithObjects()
        {
            var application = new Application(
                new Table(50000, "My Table"),
                new Table(50001, "My Other Table"),
                new Page(50000, "My Page"),
                new Codeunit(50000, "My Codeunit"));
        }

        // ## Importing an existing application from a single disk file
        public static void _00300ImportingAnExistingApplicationFromASingleDiskFile()
        {
            var application = ApplicationBuilder.FromFile("mytest.txt");
        }

        // ## Adding a table
        public static void _01000AddingATable()
        {
            var application = new Application();
            var table = application.Tables.Add(new Table(50000, "My Table"));
        }

        // ## Adding a table field
        public static void _01100AddingATableField()
        {
            var application = new Application();
            var table = application.Tables.Add(new Table(50000, "My Table"));
            var field = table.Fields.Add(new IntegerTableField(1, "Entry No."));
        }

        // ## Adding a page
        public static void _02000AddingAPage()
        {
            var application = new Application();
            var page = application.Pages.Add(new Page(50000, "My Page"));
        }
    }
}

results in:

Basic operations

Creating a new application

            var application = new Application();

Initializing an application with objects

            var application = new Application(
                new Table(50000, "My Table"),
                new Table(50001, "My Other Table"),
                new Page(50000, "My Page"),
                new Codeunit(50000, "My Codeunit"));

Importing an existing application from a single disk file

            var application = ApplicationBuilder.FromFile("mytest.txt");

Adding a table

            var application = new Application();
            var table = application.Tables.Add(new Table(50000, "My Table"));

Adding a table field

            var application = new Application();
            var table = application.Tables.Add(new Table(50000, "My Table"));
            var field = table.Fields.Add(new IntegerTableField(1, "Entry No."));

Adding a page

            var application = new Application();
            var page = application.Pages.Add(new Page(50000, "My Page"));

[jhoek]

Most of this should speak for itself. I think I'd rather focus on making the object model as intuitive as possible - almost self-documenting for anyone with some C/AL development experience.