self documenting components, types and variables

[amitu]

We need documentation support in ftd. We do not believe in putting documenting along with code, as that makes translation difficult. So documentation has to live in another file, foo.ftdoc for every foo.ftd. How would foo.ftdoc would look like?

We would definitely want to include samples, especially for components, so one can auto generate component browser etc, and have previews.

We can put all the .ftdoc files in another fpm package, so one can translate the documentation package as well using upcoming fpm translation support.

About ftdoc file

Each module will have a corresponding documentation file. For mod.ftd we will have mod.ftdoc.

A mod.ftdoc file can refer to individual files for each symbol also, [email protected], in case the module is too big.

-- import: ftd.dev/docs

-- docs.module: the name of the module

optional documentation

-- end: docs.module

-- docs.variable: name of variable

optional documentation of the variable

-- end: docs.variable

-- docs.component: name

-- docs.component.sample: Name Of Example

Description

-- docs.component.sample.code:

-- ds.h1: hello

-- end: docs.component.sample.code

-- end: docs.component.sample

-- end: docs.component

View Component Source

Source feature

View Children Source

If external children has been passed to some component, we want to see the source code for them.

-- component component:
caption name:
children about:
sample list samples:

-- ftd.column:

-- h1: $component.name

-- ftd.column:
children: $component.children
-- end: ftd.column

-- show-sample: 
$loop$: $component.samples as s
sample: $s

-- end: ftd.column

-- end: component

-- record sample:
caption name:
optional body about:
children code:
-- end: sample

-- component show-sample:
sample sample:

-- ftd.column:

-- h1: $sample.name

-- ftd.column:
children: $sample.children
-- end: ftd.column

-- ds.code:
lang: ftd
body: $sample.code.SOURCE

-- ftd.column:
children: $sample.code
-- end: ftd.column

-- end: ftd.column

-- end: show-sample