Unite how to write example

[syngan]

現状では help での example の記述方法が統一されていないので、仕様を決めてほしい。 今はこんな感じのがあります。

• 結果の表示方法
  • echo で結果を書く
  • コメントで書く
  • == で書く
• 関数の呼び出し方法
  • 関数
  • どこかで代入したと思われる変数.関数
  • モジュール名.関数

例

今は以下のような記述方法があります。

echo で実行結果を書く

        :echo String.replace("fooba.bazbar", "ba.", "zzz")
        foozzzbazbar

実行例＋コメントで結果

        build_line_from_query_with_placeholders(
         \ 'SELECT * FROM cities WHERE name = ?;',
         \ ['Vancouver'])
        "=> 'SELECT * FROM cities WHERE name = "Vancouver";'

==

        dstring(123) == 123
        dstring('abc') == '"abc"'
        dstring("abc") == '"abc"'

vital#of から + echo

                Examples: >
                :let g:V = vital#of('vital')
                :echo g:V.is_number(123)
<                1 >
                :echo g:V.is_number(1.23)
<                0 >
                :echo g:V.is_number("hoge")
<                0

vital#of から + コメント

        let B = V.import('Vim.Buffer')
        echo B.is_cmdwin() " 1 if you are in command-line-window.

• [ ] vital-bitwise.txt
• [ ] vital-data-base64.txt
• [ ] vital-data-collection.txt
• [ ] vital-data-dict.txt
• [ ] vital-data-lazylist.txt
• [x] vital-data-list.txt
• [ ] vital-data-ordered_set.txt
• [x] vital-data-string.txt
• [ ] vital-data-tree.txt
• [ ] vital-database-sqlite.txt
• [ ] vital-date_time.txt
• [ ] vital-experimental-functor.txt
• [ ] vital-locale-message.txt
• [ ] vital-mapping.txt
• [ ] vital-math.txt
• [x] vital-option_parser.txt
• [ ] vital-prelude.txt
• [ ] vital-process.txt
• [ ] vital-process_manager.txt
• [x] vital-random-xor128.txt
• [ ] vital-system-cache.txt
• [x] vital-system-file.txt (#126 待ち)
• [ ] vital-system-filepath.txt
• [ ] vital-text-csv.txt
• [ ] vital-text-lexer.txt
• [ ] vital-text-ltsv.txt
• [ ] vital-text-parser.txt
• [ ] vital-vim-buffer.txt
• [ ] vital-vim-buffer_manager.txt
• [ ] vital-vim-compat.txt
• [ ] vital-vim-message.txt
• [ ] vital-web-html.txt
• [ ] vital-web-http.txt
• [ ] vital-web-json.txt
• [ ] vital-web-xml.txt
• [ ] vital.txt
• [ ] vitalizer.txt

[osyo-manga]

help に乗っているコードを quickrun.vim で動作させる事を想定するのであればvital#of から + コメントがよいですかね。 ただ、個人的には help には簡単な例（実際に動作しなくても結果がわかればおkなコード）で、実際に動作するコードとして example ファイルを別に用意するのもよいと思います。 Vim の doc だとどうなっているのかと見てみましたが、こちらも関数によって書き方は違うみたいですね。

[syngan]

結果の書き方は違っても良いとは思うのですが, 呼び出し方法やvital#of の有り無しは vital 独自なものなので、統一したほうが良いと思うのです。

[osyo-manga]

結果の書き方は違っても良いとは思うのですが, 呼び出し方法やvital#of の有り無しは vital 独自なものなので、統一したほうが良いと思うのです。

確かにそうですね。 help レベルなら vital#of がない方がすっきりしてて見やすいのかなぁ。 あとはワンライナーで書くという手も… echo vital#of("vital").import("Data.List").uniq([1, 1, 2, 3, 3, 2]) == [1, 2, 3]

[rbtnn]

個人的には、vital#of("vital")とimport("Data.List")は、１つのhelpファイルに1か所だけ示しておく。 で、各関数ごとに、s:List.uniq([1, 1, 2, 3, 3, 2]) == [1, 2, 3]のような例をいくつか示すがいいと思います。 結果の書き方はどれでもいいかな。

こんな感じで。 http://rbtnn.github.io/how-to-use-vital.vim/

[syngan]

https://github.com/vim-jp/vital.vim/compare/513c8ca87a4a...c48c5bf0fd37

お二人のご意見を参考に更新してみました。

• Intro に vital#of() と import を追加、
• 関数の説明部では vital#of() しない
• 実行例は, import した変数.関数名
• 実行結果はコメントで

ちと面倒ですが、2 行もってくればそのまま quickrun できるので確認できて素敵な感じがします。（すぐ確認できるおかげでバグがみつかりました）

[tyru]

3番目の「vital#of から + コメント」の例

    let B = V.import('Vim.Buffer')
    echo B.is_cmdwin() " 1 if you are in command-line-window.

はE114: Missing quote: "ってエラーが出るはずです。