Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: exampleタグの使う場面をドキュメントに追記 #491

Merged
merged 6 commits into from
Dec 16, 2017
Merged

feat: exampleタグの使う場面をドキュメントに追記 #491

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
668ce5f
feat: write example tag document
yumetodo Dec 8, 2017
3c324fb
fix: move notification to the top of template
yumetodo Dec 9, 2017
db7b0b1
Revert "fix: move notification to the top of template"
yumetodo Dec 9, 2017
5ab8c56
Revert "feat: write example tag document"
yumetodo Dec 9, 2017
f5a5c15
feat: rewrite notification on the top of template
yumetodo Dec 9, 2017
a6c520e
partial revert: 5ab8c56
yumetodo Dec 9, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions editors_doc/class_template_page.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@ namespace std {
## 概要
(ここには、クラスの概要を記述します。必須事項です。)

(サンプルコードが必要な場合は`example`タグを付け、コンパイル・実行可能にすることを検討してください。(ref: [cppref特有の拡張構文](specialized.md)))
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

「概要」にサンプルコードを書くことは無いと思うので、記載の位置が変な気が
しました。で、ここじゃなくて「例」のところに書けばいいのでは？と思って
見に行くと、すでに example タグは付いてますしコメントで言及もありました。
そっちに "(ref: cppref特有の拡張構文)" を追加するだけでよかったりしませんか？
（いっしょに編集されてるほかのページもまとめての話です。）

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@k-satoda 本提案の主旨として、

#487 (comment)

以上の @yumetodo さんのコメントにあるように、以下のような点が背景にあります。

  1. サンプルコードは「例」の中に書かれているとは限らない（その例外がたくさんあることが判明した）
  2. どのコードをサンプルコードとして扱った方が良いのか明文化されていない
  3. サンプルコードには基本的に example タグを付けることが望ましい（という風に僕が方針を示した）

このため、説明文に関してはご指摘のように「例」だけに書かれているのでは分かりづらいので、「どこでもサンプルコードを書いてよい」という風に奨励する意図を書く必要があります。

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@saki7 「例」以外のコードブロックにも example をつけるおねがいは
いっしょに追加されてる example タグの説明に書かれているので、
新しく編集する人も「cpprefjpを編集するには」→「cpprefjp特有の拡張構文」
と読み進めれば拾えるようにはなっていそうです。

「新規ページ作成者さんが必ず読むところに重ねての注意が欲しい」という
ことなら文書構造とは関係ない話なので「概要」の一部として書くのではなく
テンプレ先頭に上記文書への参照を置いたほうがいいんじゃないかと思いました。

「どこでも～」という意図を考えてもやっぱり「概要」の中で言及することは
合わないように思います。現状の「例」でのみ言及されている状態を問題とする
なら「概要」と「例」でのみ言及されている状態にしても解決とはいえなさそうで。

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

「概要」にサンプルコードを書くことは無いと思うので

あります。
ex.)

「新規ページ作成者さんが必ず読むところに重ねての注意が欲しい」という
ことなら文書構造とは関係ない話なので「概要」の一部として書くのではなく
テンプレ先頭に上記文書への参照を置いたほうがいいんじゃないかと思いました。

「概要」と「例」でのみ言及されている状態にしても解決とはいえなさそうで。

# page_title (ページのタイトルです)

これの直下に、ということですか？

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

僕は現状の書き方でもOKですが、 @k-satoda さんの指摘のように記載場所に違和感があるということも少し分かります。

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@yumetodo なるほど、概要を示すにあたって多少長くなってでも
コードを示したほうが手っ取り早いことはありますね。気づいてませんでした。

「テンプレ先頭に」はタイトルよりも上のつもりでした。タイトルの書き方に
関する情報が参照先の文書に載っててもおかしくはないと思いますし。
ただし、機械処理とか、なんか支障が出るようなら下でもいいと思います。


(必要な項目を省略する場合には、「(執筆中)」と書いておいてください。)

## メンバ関数
Expand Down
2 changes: 2 additions & 0 deletions editors_doc/function_template_page.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ void definition(); // 関数・変数・定数の宣言を記述します。
## 概要
(ここには、関数・変数・定数の概要を記述します。必須事項です。)

(サンプルコードが必要な場合は`example`タグを付け、コンパイル・実行可能にすることを検討してください。(ref: [cppref特有の拡張構文](specialized.md)))

(必要な項目を省略する場合には、「(執筆中)」と書いておいてください。)


Expand Down
2 changes: 2 additions & 0 deletions editors_doc/header_template_page.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@

(ここには、このヘッダファイル(ライブラリ)の概要を記述します。必須事項です。)

(サンプルコードが必要な場合は`example`タグを付け、コンパイル・実行可能にすることを検討してください。(ref: [cppref特有の拡張構文](specialized.md)))

(必要な項目を省略する場合には、「(執筆中)」と書いておいてください。)

| 名前 | 説明 | 対応バージョン |
Expand Down
2 changes: 2 additions & 0 deletions editors_doc/lang_template_page.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,8 @@
## 概要
(ここには、言語機能の概要を記載します。)

(サンプルコードが必要な場合は`example`タグを付け、コンパイル・実行可能にすることを検討してください。(ref: [cppref特有の拡張構文](specialized.md)))

(必要な項目を省略する場合には、「(執筆中)」と書いておいてください。)


Expand Down
26 changes: 26 additions & 0 deletions editors_doc/specialized.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,32 @@ int main() {
}
```

## exampleタグ

includeとmain関数を含む**原則すべてのC/C++言語のコードブロック**には`example`タグをつけてください。
`example`タグが付いたコードブロックはその場で実際にコンパイル・実行することができるようになります。
たとえコンパイルエラーになる場合でも、利用者がその場でコードを書き換えて試行することを容易にするために原則つけてください。

````
```cpp example
#include <iostream>

int main()
{
std::cout << "arikitari_na_world" << std::endl;
}
```
````

つけない例としては次のような宣言が書いてあるのみのものが挙げられます。

```cpp
namespace std {
template <class T, class Allocator = allocator<T>>
class vector;
}
```

## プログラムの修飾

コードブロックの直後に特定の構文で記述することで、コードブロックの一部を修飾できます。
Expand Down
2 changes: 2 additions & 0 deletions editors_doc/type-type_template_page.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ typedef origin_type new_type;
## 概要
(ここには、型の概要を記述します。必須事項です。)

(サンプルコードが必要な場合は`example`タグを付け、コンパイル・実行可能にすることを検討してください。(ref: [cppref特有の拡張構文](specialized.md)))

(必要な項目を省略する場合には、「(執筆中)」と書いておいてください。)

これは、メンバ型等の、型の別名定義を解説するページの雛形です。
Expand Down