https://github.com/chalin/api_doc_updater

DEPRECATED - Dart API doc updater for @source directives
https://github.com/chalin/api_doc_updater

Last synced: about 19 hours ago
JSON representation

DEPRECATED - Dart API doc updater for @source directives

• Host: GitHub
• URL: https://github.com/chalin/api_doc_updater
• Owner: chalin
• License: mit
• Created: 2017-02-09T00:46:41.000Z (almost 8 years ago)
• Default Branch: master
• Last Pushed: 2017-08-12T14:48:43.000Z (over 7 years ago)
• Last Synced: 2024-11-15T23:37:35.936Z (about 2 months ago)
• Language: Dart
• Homepage:
• Size: 16.6 KB
• Stars: 1
• Watchers: 3
• Forks: 1
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# DEPRECATED - Dart API doc source-code-fragment updater

**Superseded by https://github.com/chalin/code_excerpt_updater.**

This is the repo for a simple _line-based_ **Dart API doc** updater for `{@source}` code fragment directives.

That is, the updater processes input source files line-by-line, looking for `{@source}` 

directives contained within public API markdown code blocks.

## Usage

Use the `api_doc_updater` tool to update code fragments marked with `{@source}` directives in Dart API docs.

```

Usage: api_doc_updater [OPTIONS] dart_file_or_directory...

-p, --fragment-path-prefix    Path prefix to directory containing code fragment files.

                              (Default is current working directory.)

-h, --help                    Show command help.

-i, --in-place                Update files in-place.

```

For example, you could run the updater over [AngularDart](https://github.com/dart-lang/angular2) source as follows:

`angular2> dart ../api_doc_updater/bin/api_doc_updater.dart -p doc/api/_fragments/ -i lib`

## @source syntax

Because this is a simple line-based processing tool, the `{@source}` directive syntax

is strict to avoid misinterpreting occurrences of `@source` in Dart

code (vs. public API doc comments), that are not `{@source}` code fragment directives.

The updater only processes `{@source}` directives **in public API

doc comments**; these are _expected_ to be **contained in code markdown blocks** like this:

```

/// ```lang

/// {@source "relative/path/to/fragment/file.ext" region="region-name"}

/// ...

/// ```

```

Notes:

- The `{@source` token can optionally be preceded by an (open) comment token such as

  `//` or `

    /// ```

    ///

    /// ```dart

    /// // {@source "docs/template-syntax/lib/app_component.dart" region="NgStyle"}

    /// ```

```

Given an appropriate path to the folder containing code fragment files, this

update tool would generate:

```dart

    /// ### Examples

    ///

    /// Try the [live example][ex] from the [Template Syntax][guide] page. Here are

    /// the relevant excerpts from the example's template and the corresponding

    /// component class:

    ///

    /// ```html

    /// 

    /// 


    ///   
Change style of this text!

    /// 

    ///   Italic:  |

    ///   Bold:  |

    ///   Size: 

    /// 

    ///   
Style set to: '{{styleP.style.cssText}}'

    /// 

    /// ```

    ///

    /// ```dart

    /// // {@source "docs/template-syntax/lib/app_component.dart" region="NgStyle"}

    /// bool isItalic = false;

    /// bool isBold = false;

    /// String fontSize = 'large';

    /// String fontSizePx = '14';

    /// 

    /// Map setStyle() {

    ///   return {

    ///     'font-style': isItalic ? 'italic' : 'normal',

    ///     'font-weight': isBold ? 'bold' : 'normal',

    ///     'font-size': fontSize

    ///   };

    /// }

    /// ```

```


## Tests

Repo tests can be launched from `test/main.dart`.