{"id":16582142,"url":"https://github.com/chalin/api_doc_updater","last_synced_at":"2025-10-17T03:32:33.364Z","repository":{"id":77274482,"uuid":"81391993","full_name":"chalin/api_doc_updater","owner":"chalin","description":"DEPRECATED - Dart API doc updater for @source directives","archived":false,"fork":false,"pushed_at":"2017-08-12T14:48:43.000Z","size":17,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-17T08:41:21.611Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chalin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-02-09T00:46:41.000Z","updated_at":"2017-08-12T14:45:30.000Z","dependencies_parsed_at":null,"dependency_job_id":"466c46c5-a954-42ac-ac02-e396ef63faa5","html_url":"https://github.com/chalin/api_doc_updater","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalin%2Fapi_doc_updater","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalin%2Fapi_doc_updater/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalin%2Fapi_doc_updater/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chalin%2Fapi_doc_updater/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chalin","download_url":"https://codeload.github.com/chalin/api_doc_updater/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242133971,"owners_count":20077171,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T22:31:43.387Z","updated_at":"2025-10-17T03:32:28.330Z","avatar_url":"https://github.com/chalin.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DEPRECATED - Dart API doc source-code-fragment updater\n\n**Superseded by https://github.com/chalin/code_excerpt_updater.**\n\nThis is the repo for a simple _line-based_ **Dart API doc** updater for `{@source}` code fragment directives.\nThat is, the updater processes input source files line-by-line, looking for `{@source}` \ndirectives contained within public API markdown code blocks.\n\n## Usage\n\nUse the `api_doc_updater` tool to update code fragments marked with `{@source}` directives in Dart API docs.\n\n```\nUsage: api_doc_updater [OPTIONS] dart_file_or_directory...\n\n-p, --fragment-path-prefix    Path prefix to directory containing code fragment files.\n                              (Default is current working directory.)\n\n-h, --help                    Show command help.\n-i, --in-place                Update files in-place.\n```\n\nFor example, you could run the updater over [AngularDart](https://github.com/dart-lang/angular2) source as follows:\n\n`angular2\u003e dart ../api_doc_updater/bin/api_doc_updater.dart -p doc/api/_fragments/ -i lib`\n\n## @source syntax\n\nBecause this is a simple line-based processing tool, the `{@source}` directive syntax\nis strict to avoid misinterpreting occurrences of `@source` in Dart\ncode (vs. public API doc comments), that are not `{@source}` code fragment directives.\n\nThe updater only processes `{@source}` directives **in public API\ndoc comments**; these are _expected_ to be **contained in code markdown blocks** like this:\n\n```\n/// ```lang\n/// {@source \"relative/path/to/fragment/file.ext\" region=\"region-name\"}\n/// ...\n/// ```\n```\n\nNotes:\n- The `{@source` token can optionally be preceded by an (open) comment token such as\n  `//` or `\u003c!--`.\n- Path, and region name if given, must be enclosed in double quotes.\n- `region` is optional.\n- Whitespace is significant: for example, the opening token has no space between the\n  `{` and the `@source`.\n\n## Code fragment updating\n\nThe updater does not create code fragment files, but it does expect such files to \nexist and be named following the conventions described below.\n\nFor a directive like `{@source \"dir/file.ext\" region=\"rname\"}`, the updater will search the\nfragment folder, for a file named:\n\n- `dir/file-rname.ext.txt`\u003cbr\u003e\n   or\n- `dir/file.ext.txt`\u003cbr\u003e\n   if the region is omitted\n\nIf the updater can find the fragment file, it will replace the lines contained within\nthe directive's markdown code block with those from the fragment file, indenting each\nfragment file line with the same indentation as the `{@source}` directive itself.\nFor example, if `hello.dart.txt` contains the line \"print('Hi');\" then\n\n```\n/// ```dart\n///   // {@source \"hello.dart\"}\n///   print('Bonjour');\n/// ```\n```\n\nwill be updated to\n\n```\n/// ```dart\n///   // {@source \"hello.dart\"}\n///   print('Hi');\n/// ```\n```\n\n## Example\n\nConsider the following API doc excerpt from the\n[NgStyle](https://webdev.dartlang.org/angular/api/angular2.common/NgStyle-class) class.\n\n```dart\n    /// ### Examples\n    ///\n    /// Try the [live example][ex] from the [Template Syntax][guide] page. Here are\n    /// the relevant excerpts from the example's template and the corresponding\n    /// component class:\n    ///\n    /// ```html\n    /// \u003c!-- {@source \"docs/template-syntax/lib/app_component.html\" region=\"NgStyle\"} --\u003e\n    /// ```\n    ///\n    /// ```dart\n    /// // {@source \"docs/template-syntax/lib/app_component.dart\" region=\"NgStyle\"}\n    /// ```\n```\n\nGiven an appropriate path to the folder containing code fragment files, this\nupdate tool would generate:\n\n```dart\n    /// ### Examples\n    ///\n    /// Try the [live example][ex] from the [Template Syntax][guide] page. Here are\n    /// the relevant excerpts from the example's template and the corresponding\n    /// component class:\n    ///\n    /// ```html\n    /// \u003c!-- {@source \"docs/template-syntax/lib/app_component.html\" region=\"NgStyle\"} --\u003e\n    /// \u003cdiv\u003e\n    ///   \u003cp [ngStyle]=\"setStyle()\" #styleP\u003eChange style of this text!\u003c/p\u003e\n    /// \n    ///   \u003clabel\u003eItalic: \u003cinput type=\"checkbox\" [(ngModel)]=\"isItalic\"\u003e\u003c/label\u003e |\n    ///   \u003clabel\u003eBold: \u003cinput type=\"checkbox\" [(ngModel)]=\"isBold\"\u003e\u003c/label\u003e |\n    ///   \u003clabel\u003eSize: \u003cinput type=\"text\" [(ngModel)]=\"fontSize\"\u003e\u003c/label\u003e\n    /// \n    ///   \u003cp\u003eStyle set to: \u003ccode\u003e'{{styleP.style.cssText}}'\u003c/code\u003e\u003c/p\u003e\n    /// \u003c/div\u003e\n    /// ```\n    ///\n    /// ```dart\n    /// // {@source \"docs/template-syntax/lib/app_component.dart\" region=\"NgStyle\"}\n    /// bool isItalic = false;\n    /// bool isBold = false;\n    /// String fontSize = 'large';\n    /// String fontSizePx = '14';\n    /// \n    /// Map\u003cString, String\u003e setStyle() {\n    ///   return {\n    ///     'font-style': isItalic ? 'italic' : 'normal',\n    ///     'font-weight': isBold ? 'bold' : 'normal',\n    ///     'font-size': fontSize\n    ///   };\n    /// }\n    /// ```\n```\n\n## Tests\n\nRepo tests can be launched from `test/main.dart`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchalin%2Fapi_doc_updater","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchalin%2Fapi_doc_updater","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchalin%2Fapi_doc_updater/lists"}