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 ?

MediaWiki PHP code base
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:
 * 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 http://svn.wikimedia.org/doc/. Also contains archives of older versions of MediaWiki
 * Navigational features:
 * Todo List
 * Deprecation List
 * Bug List (not sure what that is)
 * Modules 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
 * 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,  ,   and  . The following functions are also re-used to extract documentation information:  ,  ,  ,
 * 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 [/api.php /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  instead of  . And of course the use of.
 * 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 http://svn.wikimedia.org/doc/).

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  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

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  library (,  ,  , etc.) as well as for jQuery plugins.
 * Documentation for object constructor that shows the following in one view:
 * 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  as well as an overview of all   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)
 * MediaWiki version information (either something like "since MW .." and/or doc archive per MW-version)

Extension:DocBrowser
An extension that would contain support for several sources, configureable in LocalSettings.php (or, like CodeReview's RepoAdmin).
 * Examples:
 * Parameters:
 * Parameters:
 * Parameters:
 * Parameters:
 * Parameters:
 * Parameters:
 * Parameters:
 * Parameters:
 * Parameters:
 * Parameters:
 * Parameters:
 * Parameters:
 * Parameters:
 * Parameters:
 * Parameters:

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.
 * Note

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  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.