Requests for comment/Documentation overhaul

Request for comment (RFC)
Documentation overhaul
Component	General
Creation date	15 December 2011
Author(s)	Timo Tijhof
Document status	accepted Accepted, please implement. -- Tim Starling (talk) 06:29, 17 July 2013 (UTC)[reply]

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 (@todo)
Deprecation List (@deprecated)
Bug List (not sure what that is)
Modules (@ingroup) 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 maintenance scripts (such as Manual:refreshLinks.php)
Information about hooks (currently kept in hooks.txt and Manual:Hooks sub pages)
Global variables (Manual:Global object variables, Manual:Configuration settings)

MediaWiki API modules

Writing: The documentation for MediaWiki API modules is written as PHP strings and arrays inside a the module classes in the following methods getParamDescription, getDescription, getHelpUrls and getExamples. The following functions are also re-used to extract documentation information: getAllowedParams, mustBePosted, isWriteMode,
Format: PHP strings and arrays of strings
Parser: The MediaWiki class "ApiHelp" parses these for each module
Location: Run on-the-fly when accessing /api.php of any wiki. Such as www.mediawiki.org/w/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 api.php?action=help&modules=protect or api.php?action=help&querymodules=categorymembers

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 @param name {Type} description instead of @param name Type: description. And of course the use of @constructor.
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 api.php 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
- ~~Possible error codes~~ (removed in Gerrit change 152760 as being basically impossible to keep up-to-date)

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 mediaWiki.js library (mw.html, mw.message, mw.Map, etc.) as well as for jQuery plugins.
Documentation for object constructor that shows the following in one view:
Map, Message, ..
- 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 mw.html.element() as well as an overview of all mw.html 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 Special:DocAdmin, like CodeReview's RepoAdmin).

Examples

Special:DocBrowser/API
Special:DocBrowser/API/opensearch
Special:DocBrowser/API/query/list
Special:DocBrowser/API/query/list/allimages
- Parameters: title=Special:DocBrowser & version=mwself & doc=API & id=query/list/allimages
Special:DocBrowser/mwJS
Special:DocBrowser/mwJS/Map
Special:DocBrowser/mwJS/html
Special:DocBrowser/mwJS/html.element
Special:DocBrowser/Hooks
Special:DocBrowser/Hooks/MakeGlobalVariablesScript?version=1.18
- Parameters: title=Special:DocBrowser & version=1.18 doc=Hooks & id=MakeGlobalVariablesScript
Special:DocBrowser/Hooks?prefix=Parser
Special:DocBrowser/Hooks?group=Page Rendering
- Parameters: title=Special:DocBrowser & version=mwself doc=Hooks & hooksgroup=Page%20Rendering

Note

These only covers the program interface, it does not cover (for example) the points listed under 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 $wgDocBrowserStandalonePattern = '//docs.mediawiki.org/$1'; 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 (@constructor, @param, @context, @return).