非推奨の書き方

[faithandbrave]

C++14でrandom_shuffle()が非推奨になることもあって、cpprefjpサイト内での、非推奨の書き方を決めたいと思います。

非推奨を示す必要があるのは、少なくても以下の2ヵ所です。

1. ヘッダまたはクラスページの、機能表
2. クラス、関数の解説ページ

機能表については、「対応バージョン」列を使用して「C++14から非推奨」のように書くのがいいと思います。

クラス、関数の解説ページについては、iOS SDKのリファレンスを参考に、

https://developer.apple.com/library/ios/documentation/MediaPlayer/Reference/MPMoviePlayerController_Class/DeprecationAppendix/AppendixADeprecatedAPI.html#//apple_ref/occ/instp/MPMoviePlayerController/backgroundColor

見出し2で「C++XXから非推奨」と書き、その下に非推奨となった経緯の説明を入れる、というのでどうでしょう。

[ghost]

私はそれでいいと思います。

見出し2で「C++XXから非推奨」と書き、その下に非推奨となった経緯の説明を入れる、というのでどうでしょう。

これに関してはどこに「C++XXから非推奨」と書くかも決めなければならないと思います。

「バージョン」の項と離れるのが少し気になるのですが、私としてはすぐに目に入ってほしいので、宣言のすぐ下、概要の上あたりに「非推奨」の項目があればいいかと考えてます。

[faithandbrave]

私は、 @sscrisk さんに言われるまで「概要」の下くらいかと思っていましたが、言われてみると概要の上でもいい気がしてきました。
ちょっと考えます。

[ghost]

考えが変わりました。

MSDNでは、「非推奨」にあたる項目はなく、概要にあたる冒頭に deprected だとか no longer supported だとか書いてるようです。

C++14でgetsが削除されたようですし、今後仮に「削除」にあたる項目も追加となるとうっとうしい気もしてきました。
「概要」の冒頭に、(見出しは作らず)「非推奨」や「削除」について書くMSDNスタイルはどうでしょうか。ただし、定型文を用いる形で。

[faithandbrave]

たしかに、非推奨になったらシステム的に警告が出るので、「なぜ非推奨なのか」という説明は、最小限でいいかもしれませんね。大事なのは非推奨になったという事実で、説明は飽くまで補完的なものということで。
非推奨や削除には、exportのような例外を除いて代替手段が必ずあるので、その機能へのリンクくらいは貼りたいですが。

MSDNの参考になるページへのURLがあったら教えてもらえると助かります。(探すキーワードがよくわからない)

[ghost]

このあたり
-access (CRT)
-SHRegGetBoolValueFromHKCUHKLM function (Windows)

改めて検索してみましたが、大分表現にばらつきがありますね。
-<strstream>
-CreateToolbarEx function (Windows)
-SECURELOCK enumeration (Windows)
-Win32_LogicalMemoryConfiguration class (Windows)
など。

[faithandbrave]

ありがとうございます。

• access : 情報がばっさり削除され、「この関数のサポートは終了したので、代わりにxxxを使うこと」とだけ書いてある。
• SHRegGetBoolValueFromHKCUHKLM : ページ先頭にThis function is no longer supported.と書かれていて、それ以外はリファレンス情報がそのまま載ってる。

私は、以下の方針にするのがいいと感じました。やはり、非推奨をページの先頭に書いて目立たせる他に、その詳細も書きたいです。

1. 概要の上に、以下のように記載する。

この関数は、C++14から非推奨である。代わりにxxxを使用すること。

削除になった場合：

この関数は、C++14から非推奨となり、C++17で削除された。代わりにxxxを使用すること。

1. 非推奨の詳細情報を、備考の下に、見出し2で記載する。

##非推奨の詳細(C++14)
この関数は、xxxという理由で非推奨になった。代わりにyyyを使用すること。

削除の場合：

##削除の詳細(C++17)
この関数は、xxxという理由でC++14非推奨となり、C++17で削除された。代わりにyyyを使用すること。

[ghost]

私は、以下の方針にするのがいいと感じました。

私は賛成。++vote

[faithandbrave]

ありがとうございます！
今週いっぱいくらいまで、他の方の意見を募集して決めまーす。

[faithandbrave]

とくに反対意見がなさそうなので、これで進めたいと思います。
ひとまず、私の方がこの方針でrandom_shuffle()のページを修正しますので、その修正をもってこのIssueを閉じようと思います。

[faithandbrave]

以下のコミットで対応しました。

b8a1bdd

以降は、この関数を参考に非推奨化の記述を行ってください。