Unite how to write example

syngan commented 10 years ago

現状では 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 commented 10 years ago

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

syngan commented 10 years ago

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

osyo-manga commented 10 years ago

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

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

rbtnn commented 10 years ago

個人的には、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 commented 10 years ago

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

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

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

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

tyru commented 10 years ago

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

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

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

vim-jp / vital.vim