| Index: trunk/extensions/Translate/MessageGroups.php |
| — | — | @@ -725,8 +725,13 @@ |
| 726 | 726 | } |
| 727 | 727 | |
| 728 | 728 | /** |
| 729 | | - * @todo: needs documentation |
| 730 | | - * @deprecated |
| | 729 | + * Group for messages that can be controlled via a page in MediaWiki namespace. |
| | 730 | + * |
| | 731 | + * In the page comments start with # and continue till the end of the line. |
| | 732 | + * The page should contain list of page names in MediaWiki namespace, without |
| | 733 | + * the namespace prefix. Use underscores for spaces in page names, since |
| | 734 | + * whitespace separates the page names from each other. |
| | 735 | + * @ingroup MessageGroups |
| 731 | 736 | */ |
| 732 | 737 | class WikiMessageGroup extends MessageGroupOld { |
| 733 | 738 | protected $source = null; |
| — | — | @@ -745,13 +750,12 @@ |
| 746 | 751 | |
| 747 | 752 | /** |
| 748 | 753 | * Fetch definitions from database. |
| | 754 | + * @return \array Array of messages keys with definitions. |
| 749 | 755 | */ |
| 750 | 756 | public function getDefinitions() { |
| 751 | 757 | $definitions = array(); |
| 752 | 758 | |
| 753 | | - /** |
| 754 | | - * In theory could have templates that are substitued |
| 755 | | - */ |
| | 759 | + // In theory the page could have templates that are substitued |
| 756 | 760 | $contents = wfMsg( $this->source ); |
| 757 | 761 | $contents = preg_replace( '~^\s*#.*$~m', '', $contents ); |
| 758 | 762 | $messages = preg_split( '/\s+/', $contents ); |
| — | — | @@ -773,7 +777,7 @@ |
| 774 | 778 | * |
| 775 | 779 | * @param $key \string Key of the message. |
| 776 | 780 | * @param $code \string Language code. |
| 777 | | - * @todo Document return value (<code>isset( $data[$title][0] ) ? $data[$title][0] : null;<code> from TranslateUtils::getMessageContent). |
| | 781 | + * @return \types{\string,\null} The translation or null if it doesn't exists. |
| 778 | 782 | */ |
| 779 | 783 | public function getMessage( $key, $code ) { |
| 780 | 784 | global $wgContLang; |
| — | — | @@ -787,8 +791,8 @@ |
| 788 | 792 | } |
| 789 | 793 | |
| 790 | 794 | /** |
| 791 | | - * @todo: needs documentation |
| 792 | | - * @deprecated |
| | 795 | + * Wraps the translatable page sections into a message group. |
| | 796 | + * @ingroup PageTranslation |
| 793 | 797 | */ |
| 794 | 798 | class WikiPageMessageGroup extends WikiMessageGroup { |
| 795 | 799 | protected $title; |
| — | — | @@ -860,7 +864,7 @@ |
| 861 | 865 | * |
| 862 | 866 | * @param $key \string Key of the message. |
| 863 | 867 | * @param $code \string Language code. |
| 864 | | - * @return Mixed Stored translation or null. |
| | 868 | + * @return \mixed Stored translation or null. |
| 865 | 869 | */ |
| 866 | 870 | public function getMessage( $key, $code ) { |
| 867 | 871 | if ( $code === 'en' ) { |
| — | — | @@ -906,7 +910,8 @@ |
| 907 | 911 | } |
| 908 | 912 | |
| 909 | 913 | /** |
| 910 | | - * @todo: needs documentation |
| | 914 | + * Factory class for accessing message groups individually by id or |
| | 915 | + * all of them as an list. |
| 911 | 916 | */ |
| 912 | 917 | class MessageGroups { |
| 913 | 918 | public static function init() { |
| — | — | @@ -936,8 +941,9 @@ |
| 937 | 942 | } |
| 938 | 943 | |
| 939 | 944 | /** |
| 940 | | - * Manually reset groups when dependencies cannot |
| 941 | | - * detect those automatically |
| | 945 | + * Manually reset group cache. |
| | 946 | + * |
| | 947 | + * Use when automatic dependency tracking fails. |
| 942 | 948 | */ |
| 943 | 949 | public static function clearCache() { |
| 944 | 950 | $key = wfMemckey( 'translate-groups' ); |
| — | — | @@ -1004,9 +1010,7 @@ |
| 1005 | 1011 | if ( !empty( $conf['AUTOLOAD'] ) && is_array( $conf['AUTOLOAD'] ) ) { |
| 1006 | 1012 | $dir = dirname( $configFile ); |
| 1007 | 1013 | foreach ( $conf['AUTOLOAD'] as $class => $file ) { |
| 1008 | | - /** |
| 1009 | | - * For this request and for caching. |
| 1010 | | - */ |
| | 1014 | + // For this request and for caching. |
| 1011 | 1015 | $wgAutoloadClasses[$class] = "$dir/$file"; |
| 1012 | 1016 | $autoload[$class] = "$dir/$file"; |
| 1013 | 1017 | } |
| — | — | @@ -1030,6 +1034,11 @@ |
| 1031 | 1035 | wfDebug( __METHOD__ . "-end\n" ); |
| 1032 | 1036 | } |
| 1033 | 1037 | |
| | 1038 | + /** |
| | 1039 | + * Fetch a message group by id. |
| | 1040 | + * @param $id \string Message group id. |
| | 1041 | + * @return Message group or null if it doesn't exist. |
| | 1042 | + */ |
| 1034 | 1043 | public static function getGroup( $id ) { |
| 1035 | 1044 | self::init(); |
| 1036 | 1045 | |
| — | — | @@ -1052,9 +1061,7 @@ |
| 1053 | 1062 | } elseif ( strpos( $id, 'page|' ) === 0 ) { |
| 1054 | 1063 | list( , $title ) = explode( '|', $id, 2 ); |
| 1055 | 1064 | |
| 1056 | | - /** |
| 1057 | | - * Check first if it valid page title at all. |
| 1058 | | - */ |
| | 1065 | + // Check first if it valid page title at all. |
| 1059 | 1066 | if ( !Title::newFromText( $title ) ) { |
| 1060 | 1067 | return null; |
| 1061 | 1068 | } |
| — | — | @@ -1066,6 +1073,7 @@ |
| 1067 | 1074 | } |
| 1068 | 1075 | } |
| 1069 | 1076 | |
| | 1077 | + /// @todo make protected |
| 1070 | 1078 | public $classes; |
| 1071 | 1079 | private function __construct() { |
| 1072 | 1080 | self::init(); |
| — | — | @@ -1079,6 +1087,10 @@ |
| 1080 | 1088 | return $instance; |
| 1081 | 1089 | } |
| 1082 | 1090 | |
| | 1091 | + /** |
| | 1092 | + * Get all enabled message groups. |
| | 1093 | + * @return \array |
| | 1094 | + */ |
| 1083 | 1095 | public function getGroups() { |
| 1084 | 1096 | if ( $this->classes === null ) { |
| 1085 | 1097 | $this->classes = array(); |