NepenthesOdyssey: 1 revision imported

2025-02-25T09:35:27Z

1 revision imported

New page

{{RFC
| created = 2011-12-15
| authors = [[User:Krinkle|Timo Tijhof]]
| decision = Accepted, please implement. -- [[User:Tim Starling|Tim Starling]] ([[User talk:Tim Starling|talk]]) 06:29, 17 July 2013 (UTC)
| status = accepted
}}

Documentation in general is getting worse and more decentralized at a rapid speed. Are we going for auto-generated documentation ? Or not. If so, do we want this to go into wiki pages and be editable on the wiki, or perhaps as an extension through Special:Documentation ?

== Current state of things ==
=== MediaWiki PHP code base ===
;Writing: The documentation of our PHP code base is written in code comments throughout the php files in the source code.
;Format: The Doxygen documentation style is used.
;Parser: Parsed by Doxygen.
;Location: Periodically ran and published on https://doc.wikimedia.org/. Also contains archives of older versions of MediaWiki
;Navigational features:
* Todo List (<code>@todo</code>)
* Deprecation List (<code>@deprecated</code>)
* Bug List (not sure what that is)
* Modules (<code>@ingroup</code>) Shows all groups and the classes they contain (linked to Class documentation page) and a list of files they contain (linked to File documentation pages)
* Class List (all classes from A-Z, linked to Class documentation pages)
* Class Hierarchy (a tree based on which class extends which class, up to many levels deep. As well as a graphical presentation of this)
* File List (all files linked to their file documentation pages)
;Browser features:
* Class documentation pages (these show all the methods and variables defined in that class, including inherited methods. Grouped by public/protected etc.)
* File documentation pages (these show the classes, global functions and definitions defined in a file)
;Other
Although the primary documentation is indeed inline Doxygen, there's also on-wiki Manual:-pages that contain the following points that Doxygen currently does not provide:
* Description of '''entry-point files''' ([[Manual:Code]], such as [[Manual:load.php]])
* Description of '''[[Manual:Maintenance_scripts#List_of_maintenance_scripts|maintenance scripts]]''' (such as [[Manual:refreshLinks.php]])
* Information about '''hooks''' (currently kept in {{git file|file=docs/hooks.txt|text=hooks.txt}} and [[Manual:Hooks]] sub pages)
* '''Global variables''' ([[Manual:Global object variables]], [[Manual:Configuration settings]])

=== MediaWiki API modules ===

{{ambox|type=warning|text=The content of this section is outdated. API documentation is now provided via i18n messages. [[Special:ApiHelp|ApiHelp]] produces HTML with links and anchors. If you have checked or updated this page and found the content to be suitable, please remove this notice.}}[[Category:Outdated pages{{#translation:}}]]

;Writing: The documentation for MediaWiki API modules is written as PHP strings and arrays inside a the module classes in the following methods <code>getParamDescription</code>, <code>getDescription</code>, <code>getHelpUrls</code> and <code>getExamples</code>. The following functions are also re-used to extract documentation information: <code>getAllowedParams</code>, <code>mustBePosted</code>, <code>isWriteMode</code>,
;Format: PHP strings and arrays of strings
;Parser: The MediaWiki class "ApiHelp" parses these for each module
;Location: Run on-the-fly when accessing <code>/api.php</code> of any wiki. Such as [{{SERVER}}{{SCRIPTPATH}}/api.php {{SERVERNAME}}{{SCRIPTPATH}}/api.php] (which is for the version of MediaWiki that is currently deployed on WMF wikis) or at your own localhost at any given moment.
;Navigational features:
* Index (shows all modules and all documentation; no navigation from this)
;Browser features:
* Per-module filter by opening urls like <code>api.php?action=help&modules=protect</code> or <code>api.php?action=help&querymodules=categorymembers</code>

=== MediaWiki JavaScript library ===

;Writing: The documentation doesn't have a final output location yet. So far we've been writing it similarly to the PHP code: inside the files above the code it's documenting. Note that, due to the lack of a parser for these comments, people have written JavaScript documentation on-wiki at [[ResourceLoader/Default modules]]
;Format: ''Untitled''. So far it's been doxygen-ish, except for the trend of using <code style="white-space: nowrap;">@param name {Type} description</code> instead of <code style="white-space: nowrap;">@param name Type: description</code>. And of course the use of <code>@constructor</code>.
;Parser: ''none''.
;Location: ''none'' (you have to dive into the code to read the function documentation). The hand-written [[ResourceLoader/Default modules]] page covers most of the modules.
;Navigational features: ''none''
;Browser features: ''none''

== Specification ==

This specification will not include PHP code base documentation. The PHP doxygen solution is acceptable. Although it's not pretty or integrated into the wiki (ie. a special page), neither does it have a good search function, it has a lot of other features and most importantly, it does it well (it understands PHP very well. Such as classes that extend each other, methods that are inherited, which arguments a function takes etc.) and the navigation features of its output are very nice (look at https://doc.wikimedia.org/).

What we would like to improve is the documentation for the API, Extension hooks and the JavaScript library. A web accessible solution that preferably is integrated into MediaWiki.org somehow.

=== Features for API doc ===
The following are features that we currently have on <code>api.php</code> or on the on-wiki documentation, as well as some extra features that are currently not available but should be available in our implementation.

* A navigational structure that allows browsing pages or anchored sections on larger pages (e.g. permalinks) for each of the following:
** modules
** querymodules
** actions
* Search function that searches though module names and their descriptions
* Documentation per-module that shows:
** a short description
** MediaWiki version information (either something like "since MW .." and/or archive per MW-version)
** whether POST is required
** which user rights are needed
** parameter names and descriptions, valid values for these parameters (if MULTI), the prefix (if applicable), default value and whether optional or required.
** Example queries and their result
** <s>Possible error codes</s> <small>(removed in {{gerrit|152760}} as being basically impossible to keep up-to-date)</small>

=== Features for JavaScript doc ===
A good example is http://api.jquery.com/

* A navigational structure that allows browsing pages or anchored sections on larger pages (e.g. permalinks) for each of the object members of the <code>mediaWiki.js</code> library (<code>mw.html</code>, <code>mw.message</code>, <code>mw.Map</code>, etc.) as well as for jQuery plugins.
* Documentation for object constructor that shows the following in one view:
*:''<code>Map</code>, <code>Message</code>, ..''
** Function documentation of the root function. And possibility to add examples.
** Variable and function documentation of the object members ('static members') And possibility to add examples.
** Function documentation of the constructor prototypers ('public members') And possibility to add examples.
* Documentation for every public method and overview for sub-libraries
** Function documentation for methods like <code>mw.html.element()</code> as well as an overview of all <code>mw.html</code> methods with a description and some examples of how to use them together.
** MediaWiki version information (either something like "since MW .." and/or doc archive per MW-version)

== Implementation ideas ==

=== Extension:DocBrowser ===
An extension that would contain support for several sources, configureable in LocalSettings.php (or {{blue|Special:DocAdmin}}, like CodeReview's RepoAdmin).
;Examples:
* {{blue|Special:DocBrowser/API}}
* {{blue|Special:DocBrowser/API/opensearch}}
* {{blue|Special:DocBrowser/API/query/list}}
* {{blue|Special:DocBrowser/API/query/list/allimages}}
** Parameters: <code>title=Special:DocBrowser & version=mwself & doc=API & id=query/list/allimages</code>
* {{blue|Special:DocBrowser/mwJS}}
* {{blue|Special:DocBrowser/mwJS/Map}}
* {{blue|Special:DocBrowser/mwJS/html}}
* {{blue|Special:DocBrowser/mwJS/html.element}}
* {{blue|Special:DocBrowser/Hooks}}
* {{blue|1=Special:DocBrowser/Hooks/MakeGlobalVariablesScript?version=1.18}}
** Parameters: <code>title=Special:DocBrowser & version=1.18 doc=Hooks & id=MakeGlobalVariablesScript</code>
* {{blue|1=Special:DocBrowser/Hooks?prefix=Parser}}
* {{blue|1=Special:DocBrowser/Hooks?group=Page Rendering}}
** Parameters: <code>title=Special:DocBrowser & version=mwself doc=Hooks & hooksgroup=Page%20Rendering</code>

;Note
These only covers the program interface, it does not cover (for example) the points listed under [[##MediaWiki_PHP_code_base|Other]] such as entry-point files, maintenance scripts and global variables.

===Standalone===
Set up "docs.mediawiki.org" as a stand-alone version of the docs, without the wiki around it.
*Implemention idea 1:
**Point it to the same wiki as for "www.mediawiki.org" and rewrite / to "/wiki/Special:DocBrowser/$1[?&]format=standalone", and configure <code>$wgDocBrowserStandalonePattern = '//docs.mediawiki.org/$1';</code> The Extension would, if it matches, take over output and do it's own thing.
*Implemention idea 2:
** DocBrowser would provide a maintenance script that exports .html files, which we then sync to the docroot for docs.mediawiki.org.
** This option is probably better. One of the things we could do is provide option to point to the phase3-root, so it can be ran for different branches as well.

----
''Footnotes'':
* Function documentation: This is the comment written right above the function itself. Usually containing a short description and one or more of the following keywords (<code>@constructor</code>, <code>@param</code>, <code>@context</code>, <code>@return</code>).

== See also ==
* [[Thread:Project:Current issues/Api documentation bot#Api documentation bot 6231]]

[[Category:Documentation]]
[[Category:Requests for comment]]

Requests for comment/Documentation overhaul - Revision history

NepenthesOdyssey: 1 revision imported