path: root/files/ja/mdn/contribute/howto/write_interface_reference_documentation/index.html

---
title: Mozilla インターフェイスのリファレンス文書の書き方
slug: MDN/Contribute/Howto/Write_interface_reference_documentation
tags:
  - Guide
  - Howto
  - MDN Meta
translation_of: MDN/Contribute/Howto/Write_interface_reference_documentation
---
<p>{{MDNSidebar}}</p>

<p>この記事では、 Mozilla のインターフェイスのために、適切にフォーマットされた有用なドキュメントを作成する方法を示します。それぞれのインターフェイスは、記事のタイトルをインターフェイスの名前にして、個別の記事で文書化されなければなりません。</p>

<div class="blockIndicator warning">
<p><strong>重要:</strong> 私たちは、Mozilla 内部のインターフェイス (ほとんどが nsI で始まる) を MDN 上で積極的にドキュメント化することはもうありません。これらのドキュメントが将来どこに置かれるべきかの最終決定はまだ検討中ですが、それまでの間、あなたの時間を使って MDN にドキュメントを書くことは一般的にお勧めしません。</p>
</div>

<h2 id="Learn_by_example" name="Learn_by_example">Learn by example</h2>

<p>See our <a href="/ja/docs/MDN/Contribute/Howto/Write_interface_reference_documentation/Sample_interface_document" title="Project:Sample_interface_document">sample interface document</a> for a fictional interface that implements all the features of a complete interface reference document. This article can serve as a helpful template when documenting an interface.</p>

<h2 id="Interface_reference_sections" name="Interface_reference_sections">Interface reference sections</h2>

<p>Each interface reference article has at least an introduction section (which has no heading). The introduction should provide an overview of what the interface is used for.</p>

<p>Following the table of contents, use the {{TemplateLink("IFSummary")}} macro to describe the location and status of the interface in the source tree.</p>

<p>The parameters to the <code>IFSummary</code> macro are:</p>

<dl>
 <dt>Path of the IDL file defining the interface</dt>
 <dd>This is used to create a link to the interface's IDL on MXR so the reader can refer to it if they wish.</dd>
 <dt>Parent interface</dt>
 <dd>This is the name of the interface upon which the interface being documented is based. This will be turned into a link to that interface in the interface reference and displayed.</dd>
 <dt>scriptable/not scriptable</dt>
 <dd>A string indicating whether the interface is scriptable or not. You must use either "scriptable" or "not scriptable" (these are, however, case insensitive). This will be turned into an appropriate indicator in the box, colored green for scriptable interfaces or red for non-scriptable ones. The indicator will also include a link to an article explaining what this means.</dd>
 <dt>Last changed in what Gecko version</dt>
 <dd>This is a string indicating the version of Gecko in which the interface was last changed. It should be a string in standard Gecko version format, such as "1.9" or "1.9.2" or even "1.9.1.6".</dd>
 <dt>Summary{{Optional_Inline}}</dt>
 <dd>A brief textual summary of what the interface does. Should be just a sentence or two. This is only optional for backward compatibility with old interface documents using the now deprecated InterfaceStatus macro (which now calls through to this one). You should <em>always</em> provide this.</dd>
 <dt>Version introduced{{Optional_Inline}}</dt>
 <dd>If you know the version of Gecko in which the interface was introduced, include that here. This will trigger the inclusion of a version timeline diagram showing the availability of the interface in relation to the history of Gecko.</dd>
 <dt>Version deprecated{{Optional_Inline}}</dt>
 <dd>If the interface is deprecated, include that here. This will be used when drawing the version timeline diagram.</dd>
 <dt>Version obsoleted{{Optional_Inline}}</dt>
 <dd>Similarly, if the interface is obsolete and no longer available at all, include the Gecko version in which that took effect.</dd>
</dl>

<dl>
 <dd>{{todo("Should describe the 'Implemented by' section here")}}</dd>
</dl>

<p>All other sections are usually optional, but may be necessary depending on the interface. The optional sections are:</p>

<h3 id="Method_overview" name="Method_overview">Method overview</h3>

<p>The method overview is a table that simply lists all the method signatures for each method provided by the interface. The method's name should be a clickable link to the method description itself. Ideally, the methods should be listed in alphabetical order.</p>

<p>If a method supports multiple types for a given input parameter, you can list them using the format [type1, type2, ..., typeN].</p>

<h3 id="Attributes" name="Attributes">Attributes</h3>

<p>The attributes section consists of a three column table. The first column contains the names of each attribute offered by the interface. The second column indicates the types of each attribute; these types should be links for non-simple types. The third column should describe the attribute, explaining its use and providing any details needed. Please list the attributes in alphabetical order; you can sort the table after the fact by right-clicking in it; there's a "Sort Table" option in the contextual menu.</p>

<h3 id="Constants" name="Constants">定数</h3>

<p>Each group of constants should have a sub-section containing a table describing the relevant constants. The table should have three columns: Constant (the names of the constants), Value (their values), and Description (descriptive text explaining the use of the constant).</p>

<h3 id="Methods" name="Methods">Methods</h3>

<p>The methods section provides detailed documentation for each method offered by the interface. Within the methods section should be a subsection for each method. Each method's subsection name should include closing parentheses (such as "parseAsync()" in the {{Interface("nsIFeedProcessor")}} interface reference.</p>

<p>The methods should be listed in the same order in which they appear in the "Method overview" section.</p>

<p>Each method's subsection should begin with a description of what the method does, followed by the actual method signature itself. Each parameter to the method should be on a separate line for clarity.</p>

<p>After the method signature should come a "Parameters" subsection. In order to avoid cluttering the table of contents for the page, we use <code>&lt;h5&gt;Parameters&lt;/h5&gt;</code> to define the Parameters subsection's heading.</p>

<p>The parameters are then listed with descriptions of each parameter using definition list format. If there are no parameters, write the word 'None' under the Parameters heading.</p>

<p>If the method has a return value, include a "Return value" subsection, using the form <code>&lt;h5&gt;Return value&lt;/h5&gt;</code>. This subsection should simply explain the return value, its type, and if applicable its possible values.</p>

<p>If the method can throw exceptions, a similar "Exceptions thrown" subsection should be included, containing a definition list style list for each possible exception.</p>

<h3 id="Remarks" name="Remarks">Remarks</h3>

<p>Any general comments that apply to the interface as a whole may be placed in the Remarks section.</p>

<h3 id="See_also" name="See_also">See also</h3>

<p>If links to other interfaces, or to any other documents, might be helpful to the reader, these should be listed in the "See also" section.</p>

<h2 id="Categorizing_articles" name="Categorizing_articles">Categorizing articles</h2>

<p>Each article that documents an interface needs to be added to the Interfaces category by adding the "Interfaces" tag. Likewise, the article should have any other appropriate tags.</p>

<h2 id="Finding_articles_that_need_help" name="Finding_articles_that_need_help">Finding articles that need help</h2>

<p>Look through <a href="/ja/docs/tag/Interfaces" title="tag/Interfaces">the interface list</a> and see if any are marked as being in the category <a href="/ja/docs/tag/NeedsMarkupWork" title="tag/NeedsMarkupWork">NeedsMarkupWork</a>. These are interfaces that we know need to be reformatted into our new layout. If you clean one up, remove the line that adds it to that category.</p>