ドキュメント改善:ComponentInformationまわりの記載について

[whiteflare]

話題としては以下のドキュメントに関する改善提案です。
https://vpm.anatawa12.com/avatar-optimizer/ja/docs/developers/make-your-components-compatible-with-aao/
https://github.com/anatawa12/AvatarOptimizer/blob/master/API-Editor/ComponentInformation.cs
自分が内容を全て把握できている自信がないためdiscussionで起票させていただきます。

これらのドキュメントが対象とするのは「独自コンポーネントを作成した他の作者、ただしAAOの内部処理には詳しくない」と思うのですが、想定している対象にとっては説明が足りていないのではと考えています。
(正確には、そういった立場である自分があまりドキュメントを理解できなかったため、理解を深めると同時にドキュメント側の改善も行えないかと画策しています)

例えば、MarkEntrypoint のXMLDOCを見るに、

AvatarOptimizer/API-Editor/ComponentInformation.cs

Line 111 in 98728ed

/// Marks this component as EntryPoint component, which means has some effects to non-avatar components.

このコンポーネントをEntryPointコンポーネントとしてマークします。これはアバター以外のコンポーネントに何らかの影響を与えることを意味します。

EntryPoint についての説明は「effects to non-avatar」と記載されていて、「non-avatar」の説明が無いためそれ以上理解できませんでした。
また「意味する」は「AAOが、～のように処理する」と解釈しましたが、具体的にAAOが何を行うかが明確ではなく、その結果 MarkEndpoint をどのような場合に呼び出せば良いかが伝わらないと思っています。

提案としては、次のような内容にするのが良いと思います。

このコンポーネントをEntryPointコンポーネントとしてマークします。

EntryPointコンポーネントは、それ単体で独立して動作するものとAvatarOptimizerは解釈し、未使用コンポーネントとしてAvatarOptimizerが削除することはありません。
EntryPointコンポーネントが追加されたGameObjectも、AvatarOptimizerは使用中であると解釈します。

EntryPointコンポーネントが参照している先のコンポーネントをAvatarOptimizerに使用中であると解釈させるには、AddDependencyメソッドを呼び出して参照先を登録してください。

この内容に続いて、Renderer や PhysBone の例を列挙していくことになると思います。
// disable な Renderer であっても MarkEntryPoint しているという点が理解しきれないでいます。MarkEntryPoint はしておいて別の仕組みで要不要を判定して削除しているのではと推測していますが、そうではないとすると上記の提案内容には間違いがあるのかもしれません。

同様の問題が MarkHeavyBehaviour や MarkBehaviour にもあり、これらを呼び出した結果 AvatarOptimizer がどのように扱うかの情報が記載されていないため理解できないでいます。

AvatarOptimizer/API-Editor/ComponentInformation.cs

Lines 146 to 147 in 98728ed

	/// When you mark your some components Behaviour component, Avatar Optimizer will never change activeness of
	/// the component.

実際、削除されないことを期待して MarkBehaviour を呼び出しましたが、XMLDOCの記載に反してコンポーネントは削除されました。
activeness 自体は変更されなくなったのかもしれませんが、結果的には不要コンポーネントとして削除されたものと思います。
AvatarOptimizer の処理が何段階かに分かれていて、ただし何段階に分かれているかの情報がないため、activeness まわりの情報が伝わらなくなってしまったのではと推測しています。

[anatawa12]

とりあえずactivenessについてはisActiveやenabledを指しており、残すかどうかとは独立しています。

xmldocについては今手元で草案を書いてるのでそれを更新したらまた意見をいただきたいです。

[anatawa12]

https://github.com/anatawa12/AvatarOptimizer/blob/api-xml-doc-improvements/API-Editor/ComponentInformation.cs

とりあえずAvatar Optimizerの動作の説明を少し追加しました

[whiteflare]

こちらですかね。だいぶ読みやすくなった印象です。ありがとうございます。
4713a8f

そうか、VRCPhysBone を MarkHeavyBehaviour しておくことにより、ウェイトで紐付くメッシュが無いときに VRCPhysBone を無効にする挙動を実現している感じなのですね。
MarkHeavyBehaviour と MarkBehaviour はその用途のマークに使われるもので、MarkEntrypoint とはレベルが異なると。理解できてきました。

[anatawa12]

ブランチを間違ってました。修正しました。

そうか、VRCPhysBone を MarkHeavyBehaviour しておくことにより、ウェイトで紐付くメッシュが無いときに VRCPhysBone を無効にする挙動を実現している感じなのですね。
MarkHeavyBehaviour と MarkBehaviour はその用途のマークに使われるもので、MarkEntrypoint とはレベルが異なると。理解できてきました。

"ウェイトで紐付くメッシュが無いとき"というよりは"ウェイトで紐付くメッシュが非表示なとき"ですがだいたい認識はあっています。