📝 Add documentation comments on argument

Author: lambdalisue

denops_std/argument/README.md

@@ -7,6 +7,31 @@ const shortPattern = /^-([a-zA-Z0-9])(.*)/;
 
 /**
  * Parse string array to extract flags (-f/--flag).
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { parseFlags } from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   const args = [
+ *     "++enc=sjis",
+ *     "++ff=dos",
+ *     "-f",
+ *     "--foo=foo",
+ *     "--bar=bar",
+ *     "--bar=baz",
+ *     "hello",
+ *     "world",
+ *   ];
+ *   const [flags, residues] = parseFlags(args);
+ *
+ *   console.log(flags);
+ *   // { "f": "", "foo": "foo", "bar": ["bar", "baz"] }
+ *
+ *   console.log(residues);
+ *   // ["++enc=sjis", "++ff=dos", "hello", "world"]
+ * }
+ * ```
  */
 export function parseFlags(args: string[]): [Flags, string[]] {
   const patterns = [longPattern, shortPattern];
@@ -39,6 +64,27 @@ export function parseFlags(args: string[]): [Flags, string[]] {
 
 /**
  * Validate if `flags` has unknown attributes.
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { parse, validateFlags } from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   const args = [
+ *     "++enc=sjis",
+ *     "++ff=dos",
+ *     "-f",
+ *     "--foo=foo",
+ *     "--bar=bar",
+ *     "--bar=baz",
+ *     "hello",
+ *     "world",
+ *   ];
+ *   const [_opts, flags, _residues] = parse(args);
+ *
+ *   validateFlags(flags, ["f", "foo", "bar"]);
+ * }
+ * ```
  */
 export function validateFlags(flags: Flags, knownAttributes: string[]): void {
   Object.keys(flags).forEach((v) => {
@@ -54,6 +100,19 @@ export function validateFlags(flags: Flags, knownAttributes: string[]): void {
 
 /**
  * Format `key` and `value` to construct string array.
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { formatFlag } from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   console.log(formatFlag("f", ""));
+ *   // "-f"
+ *
+ *   console.log(formatFlag("foo", "value"));
+ *   // "--foo=value"
+ * }
+ * ```
  */
 export function formatFlag(
   key: string,
@@ -72,6 +131,28 @@ export function formatFlag(
 
 /**
  * Format `flags` to construct string array.
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { formatFlags, parse } from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   const args = [
+ *     "++enc=sjis",
+ *     "++ff=dos",
+ *     "-f",
+ *     "--foo=foo",
+ *     "--bar=bar",
+ *     "--bar=baz",
+ *     "hello",
+ *     "world",
+ *   ];
+ *   const [_opts, flags, _residues] = parse(args);
+ *
+ *   console.log(formatFlags(flags));
+ *   // "-f --foo=foo --bar=bar --bar=baz"
+ * }
+ * ```
  */
 export function formatFlags(flags: Flags, includes?: string[]): string[] {
   let entries = Object.entries(flags);

denops_std/argument/flags.ts

@@ -1,6 +1,42 @@
+/**
+ * A module to handle Vim's command arguments.
+ *
+ * @module
+ */
 import { Opts, parseOpts } from "./opts.ts";
 import { Flags, parseFlags } from "./flags.ts";
 
+/**
+ * Parse string array to extract opts, flags.
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { parse } from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   const args = [
+ *     "++enc=sjis",
+ *     "++ff=dos",
+ *     "-f",
+ *     "--foo=foo",
+ *     "--bar=bar",
+ *     "--bar=baz",
+ *     "hello",
+ *     "world",
+ *   ];
+ *   const [opts, flags, residues] = parse(args);
+ *
+ *   console.log(opts);
+ *   // { "enc": "sjis", "ff": "dos" }
+ *
+ *   console.log(flags);
+ *   // { "f": "", "foo": "foo", "bar": ["bar", "baz"] }
+ *
+ *   console.log(residues);
+ *   // ["hello", "world"]
+ * }
+ * ```
+ */
 export function parse(args: string[]): [Opts, Flags, string[]] {
   const [opts, intermediate] = parseOpts(args);
   const [flags, residue] = parseFlags(intermediate);

denops_std/argument/mod.ts

@@ -22,6 +22,31 @@ const optPattern = /^\+\+([a-zA-Z0-9-]+)(?:=(.*))?/;
 
 /**
  * Parse string array to extract opts (++opt).
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { parseOpts } from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   const args = [
+ *     "++enc=sjis",
+ *     "++ff=dos",
+ *     "-f",
+ *     "--foo=foo",
+ *     "--bar=bar",
+ *     "--bar=baz",
+ *     "hello",
+ *     "world",
+ *   ];
+ *   const [opts, residues] = parseOpts(args);
+ *
+ *   console.log(opts);
+ *   // { "enc": "sjis", "ff": "dos" }
+ *
+ *   console.log(residues);
+ *   // ["-f", "--foo=foo", "--bar=bar", "--bar=baz", "hello", "world"]
+ * }
+ * ```
  */
 export function parseOpts(args: string[]): [Opts, string[]] {
   const opts: Opts = {};
@@ -50,6 +75,30 @@ export function parseOpts(args: string[]): [Opts, string[]] {
 
 /**
  * Validate if `opts` has unknown attributes.
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { builtinOpts, parse, validateOpts } from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   const args = [
+ *     "++enc=sjis",
+ *     "++ff=dos",
+ *     "-f",
+ *     "--foo=foo",
+ *     "--bar=bar",
+ *     "--bar=baz",
+ *     "hello",
+ *     "world",
+ *   ];
+ *   const [opts, _flags, residues] = parse(args);
+ *
+ *   validateOpts(opts, ["enc", "ff"]);
+ *
+ *   // Or use `builtinOpts` to validate Vim's builtin `++opts`
+ *   validateOpts(opts, builtinOpts);
+ * }
+ * ```
  */
 export function validateOpts(opts: Opts, knownAttributes: string[]): void {
   Object.keys(opts).forEach((v) => {
@@ -61,6 +110,16 @@ export function validateOpts(opts: Opts, knownAttributes: string[]): void {
 
 /**
  * Format `key` and `value` to construct string array.
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { formatOpt } from "./mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   console.log(formatOpt("enc", "sjis"));
+ *   // "++enc=sjis"
+ * }
+ * ```
  */
 export function formatOpt(key: string, value: string | undefined): string[] {
   if (value == undefined) {
@@ -71,6 +130,28 @@ export function formatOpt(key: string, value: string | undefined): string[] {
 
 /**
  * Format `opts` to construct string array.
+ *
+ * ```typescript
+ * import { Denops } from "../mod.ts";
+ * import { formatOpts, parse } from "../argument/mod.ts";
+ *
+ * export async function main(denops: Denops): Promise<void> {
+ *   const args = [
+ *     "++enc=sjis",
+ *     "++ff=dos",
+ *     "-f",
+ *     "--foo=foo",
+ *     "--bar=bar",
+ *     "--bar=baz",
+ *     "hello",
+ *     "world",
+ *   ];
+ *   const [opts, _flags, _residues] = parse(args);
+ *
+ *   console.log(formatOpts(opts));
+ *   // "++enc=sjis ++ff=dos"
+ * }
+ * ```
  */
 export function formatOpts(opts: Opts, includes?: string[]): string[] {
   let entries = Object.entries(opts);