Requests for comment/Documentation overhaul
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 ?
Documentation overhaul | |
---|---|
Component | General |
Creation date | |
Author(s) | Timo Tijhof |
Document status | accepted Accepted, please implement. -- Tim Starling (talk) 06:29, 17 July 2013 (UTC) |
Current state of things
editMediaWiki PHP code base
edit- 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
editThe content of this section is outdated. API documentation is now provided via i18n messages. 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. |
- 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
andgetExamples
. 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
orapi.php?action=help&querymodules=categorymembers
MediaWiki JavaScript library
edit- 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
editThis 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
editThe 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
editA 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 allmw.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)
- Function documentation for methods like
Implementation ideas
editExtension:DocBrowser
editAn 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
- Parameters:
- 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
- Parameters:
- Special:DocBrowser/Hooks?prefix=Parser
- Special:DocBrowser/Hooks?group=Page Rendering
- Parameters:
title=Special:DocBrowser & version=mwself doc=Hooks & hooksgroup=Page%20Rendering
- Parameters:
- 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
editSet 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.
- Point it to the same wiki as for "www.mediawiki.org" and rewrite / to "/wiki/Special:DocBrowser/$1[?&]format=standalone", and configure
- 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
).