站长百科 | 数字化技能提升教程 数字化时代生存宝典
首页
数字化百科
电子书
▼
建站程序
开发
服务器
办公软件
开发教程
▼
服务器教程
软件使用教程
运营教程
热门电子书
▼
CSS教程
WordPress教程
导航
程序频道
推广频道
网赚频道
人物频道
网站程序
网页制作
云计算
服务器
CMS
论坛
网店
虚拟主机
cPanel
网址导航
WIKI使用导航
WIKI首页
热点词条
最新资讯
网站程序
站长人物
页面分类
使用帮助
编辑测试
创建条目
网站地图
站长百科导航
站长百科
主机侦探
IDCtalk云说
跨境电商导航
WordPress啦
站长专题
网站推广
网站程序
网站赚钱
虚拟主机
cPanel
网址导航专题
云计算
微博营销
虚拟主机管理系统
开放平台
WIKI程序与应用
美国十大主机
编辑“
WordPress:Inline Documentation
”
人物百科
|
营销百科
|
网赚百科
|
站长工具
|
网站程序
|
域名主机
|
互联网公司
|
分类索引
Xxf3325
(
讨论
|
贡献
)
2008年4月28日 (一) 15:28的版本
(新页面: This page is the start of the effort to add inline documentation to the WordPress core code to aid in future development, improvements and changes, as well as to assist others when learni...)
(差异) ←上一版本 |
最后版本
(
差异
) |
下一版本→
(
差异
)
跳转至:
导航
、
搜索
警告:您正在编辑的是本页面的旧版本。
如果您发布该更改,该版本后的所有更改都会丢失。
警告:
您没有登录。如果您做出任意编辑,您的IP地址将会公开可见。如果您
登录
或
创建
一个账户,您的编辑将归属于您的用户名,且将享受其他好处。
反垃圾检查。
不要
加入这个!
This page is the start of the effort to add inline documentation to the WordPress core code to aid in future development, improvements and changes, as well as to assist others when learning about PHP and WordPress. Use of this page and subsequent child pages is meant for developing standard methodologies and formats, as well as to ensure that there is no duplication of effort. In the best case, inline documentation should appear as close to this [http://pear.php.net/manual/en/standards.sample.php PEAR sample]. == What Should be Documented == Documenting globals gives information for phpDocumentor and others reading the source code on how the global is used. It isn't required and in most cases not necessary, since the core developers may not accept the patches. Functions and class methods are often difficult to be used without context. Documentation can offer context, but inline documentation should not be used for giving extreme examples, except for small lines of code where codex information is not immediately available. Most of the classes used in WordPress are Singletons (the entire functionality is contained in a single class), but often require initializing of properties manually. Often the question of when to use a method in a class is not clear in most situations. Newer class additions and some external libraries use multiple classes to form a library for functionality. This creates a higher learning curve as the base class (the class the developer uses that provides the functionality from all of the rest of the classes) is not clear. Adding documentation on where the class falls in the class library hierarchy provides more clarity. The properties of classes need to be documented for class documentation completeness. The PHPdoc tags for those can be found at the main site and an example can be found below. == PHPdoc Tags== PHPDoc tags work with some editors to display more information about a piece of code. It is useful to developers using those editors to understand what the purpose and where they would use it in their code. The convention for allow PHPdoc blocks is to have @since information (even if not available at the time) and @package information, which should always be "WordPress" unless it is an external library. <pre> /** * ... Description(s) here * * @package WordPress * @since 2.1 or {{@internal Unknown}}} * * ... More information if needed. */ </pre> You will not use PHPdoc comment blocks inside function and method blocks, except to document "TODO" information. All other comments inside methods and functions should not use PHPdoc comments. <pre> /** * @todo ... Description */ </pre> Or the second form can be used is most cases. <pre>/** @todo ... Description */</pre> == Mapping Includes and Requires == Documenting includes and requires can be useful to explain what relationship the included file has to the current file and why it is needed and what can be found in it. Not necessary for WordPress core files, but might be useful for your own plugins, if you split the code into logical files. <pre> /** * This file holds all of the users * custom information */ require ABSPATH.'/wp-config.php'; </pre> == File Documentation == File documentation using PHPdoc comment blocks can be used to give an overview on what the file holds and what can be found in the file. Used to its full advantage may prevent someone from exploring the file too deeply and wasting their time. Some PHPdoc tags can be applied globally to every other PHPdoc comment block for phpDocumentor sites. <pre> /** * ... Description of what is contained in file here * * @package WordPress */ </pre> == Global PHPdoc Comment Block == Often it is useful to document globals that are commonly used for the function @uses reference. It is better to have the description first as it is what the coder needs. The rest of the information might be important, @since for example, but @global tag is only useful for phpDocumentator sites. <pre> /** * ... Description * @since * @global type $varname */ </pre> == Function PHPdoc == The convention for WordPress function PHPdoc types includes the short description and long description (if applicable). The short description must include the function name with only the parenthesize '()'. The short description should not restate what the function name is, but look deeper in to what the function does (the code) and summarize that. The function name might say one thing, but actually do something completely different (the specs changed, but the usage did not). The short description is required for the documentation of the function to be considered complete. A note may be left in certain circumstances, see below, that lets others know that the short description is missing. <pre> /** * function_name() - Short Description </pre> Long descriptions should be included in most functions to give clarity to what the short description means. In most cases, the summary should only serve as a reminder to what the coder read in the long description. In rare cases, the function is so short that the summary can be used to describe the full extent of the function's purpose. It is up to the documentation author's judgment, but as a rule always try to include the long descriptions in the PHPdoc block. <pre> /** * function_name() - Short Description * * Long Description * */ </pre> It is acceptable if the function does not have parameter or return documentation to leave a note that the short and long descriptions are missing. This should only be used when you are writing documentation for a multiple functions are only leaving a note that you intentionally left that area blank for someone else or for yourself to complete later. <pre> /** * function_name() - {{@internal Missing Short Description}}} * * {{@internal Missing Long Description}}} * */ </pre> For other tags to remind yourself or others that you did not mean for the tag to be blank in that area. Other times, it should be assumed that if someone left something blank, that they meant to do so, or didn't think the description was required for others to understand the function. The information might not serve any purpose if it is available elsewhere. For example in the @uses tag for globals, if the global variable was already documented. <pre> * @uses function_name() {{@internal Missing Description}}}</pre> After the short and long description, other information is important to the coder and phpDocumentor sites. <pre> /** * function_name() - Short Description * * Long Description * * @package WordPress * @since version * * @param type $varname Description * @return type Description */ </pre> The convention for @since is to use just the version number, "2.1", or "2.3.1" and leave off any other strings. The @package information gives coders and phpDocumentor which application the function and therefore the @since application the version number belongs to. For consistency, if parameters are available, they must always be documented for every function. If the "return" keyword is used anywhere in the function, then the @return tag should be used to document that possible case. If it does not exist, then it is best to not include the tag, because if it exists, the reader might expect it to have the "return" keyword. If the function is deprecated, should not be used any longer, then the @deprecated tag along with the version and description of what to use instead should be given. Also include the @uses tag with the function name. <pre> /** * ... Descriptions * * @deprecated 2.1 Use function_name() instead. * @uses function_name() * * ... parameters and return descriptions */ </pre> == Class PHPdoc tags == The information on class PHPdoc tags to use in WordPress classes is intentionally left out. One note is that the class definition, the class properties (variables), and class methods (functions) all need to have documentation to be complete. The [http://pear.php.net/manual/en/standards.sample.php PEAR sample] should be referenced for the tags to use for each. ==Past WP-Hackers Discussions== The WP-Hackers list has a number of past discussions on adding inline documentation. In recent cases, this page was not referenced or found during the discussion. By documenting WordPress files, the discussions on WP-Hackers and elsewhere can be brought to a close if enough effort is put forth to do the work to document the files. *[http://comox.textdrive.com/pipermail/wp-hackers/2006-February/004921.html Inline Documentation] (February 2006) *[http://comox.textdrive.com/pipermail/wp-hackers/2006-February/004989.html PATCH Documentation] (February 2006) *[http://comox.textdrive.com/pipermail/wp-hackers/2007-October/015584.html Proposal for a function commenting convention ] (October 2007) ==Resources== * [http://phpxref.com/xref/wordpress/nav.html.gz?index.html.gz English Version] *[http://www.phpdoc.org/ phpDocumentor] - Auto-documentation tool for php language (phpdoc.org) *[http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html phpDocumentor Tutorial] - How to use phpDocumentor (phpdoc.org) *[http://www.zend.com/store/products/zend-studio/ Zend Studio] - PHP Development Environment (commercial product) * At aptana.tv there is [http://www.aptana.tv/movies/aptana_scriptdoc_overview/ScriptDocOverview.html a video showing the power of proper inline documentation]. Some tags are really helpful as you can see there. ==Files with Inline Documentation== For a list of current files in WordPress, see [[WordPress:WordPress Files]]. ===External Library Files=== Third party libraries should have file level documentation, but should not be part of the WordPress documentation effort. The following third party files have file level documentation. Below is the list of external files in WordPress 2.5 (1/10/2008). '''All external library files are completed''' * /wp-includes/atomlib.php * /wp-includes/class-IXR.php * /wp-includes/class-phpass.php * /wp-includes/class-phpmailer.php (does not need file level documentation because it has class level documentation) * /wp-includes/class-pop3.php * /wp-includes/class-smtp.php (does not need file level documentation because it has class level documentation) * /wp-includes/class-snoopy.php * /wp-includes/gettext.php * /wp-includes/streams.php * /wp-includes/rss.php * /wp-includes/rss-functions.php (deprecated) ===WordPress Finished Files=== These files have complete PHPdoc style documentation. Listed are the documentation writer, along with the WordPress Trac ticket number. # [http://trac.wordpress.org/ticket/5211 #5211] - /wp-settings.php - Jacob Santos (Use as an example for other files) # [http://trac.wordpress.org/ticket/4393 #4393] - /wp-includes/author-template.php - Robin Adrianse and cleanup by Jacob Santos # [http://trac.wordpress.org/ticket/5523 #5523] - /wp-includes/bookmark.php - Jacob Santos # [http://trac.wordpress.org/ticket/5521 #5521] - /wp-includes/bookmark-template.php - Jacob Santos # [http://trac.wordpress.org/ticket/5511 #5511] - /wp-includes/cache.php - Jacob Santos # [http://trac.wordpress.org/ticket/5526 #5526] - /wp-includes/canonical.php - Jacob Santos # [http://trac.wordpress.org/ticket/5528 #5528] - /wp-includes/comment-template.php - Jacob Santos (help from Peter Walker [http://trac.wordpress.org/ticket/2648 #2648]) # [http://trac.wordpress.org/ticket/5510 #5510] - /wp-includes/compat.php - Jacob Santos # [http://trac.wordpress.org/ticket/5527 #5527] - /wp-includes/default-filters.php - Jacob Santos # [http://trac.wordpress.org/ticket/5527 #5527] - /wp-includes/feed-rss2-comments.php - Jacob Santos # [http://trac.wordpress.org/ticket/5527 #5527] - /wp-includes/feed-rss2.php - Jacob Santos # [http://trac.wordpress.org/ticket/5527 #5527] - /wp-includes/feed-rdf.php - Jacob Santos # [http://trac.wordpress.org/ticket/5527 #5527] - /wp-includes/feed-atom-comments.php - Jacob Santos # [http://trac.wordpress.org/ticket/5527 #5527] - /wp-includes/feed-rss.php - Jacob Santos # [http://trac.wordpress.org/ticket/5527 #5527] - /wp-includes/feed-atom.php - Jacob Santos # [http://trac.wordpress.org/ticket/5641 #5641] - /wp-includes/kses.php - Jacob Santos # [http://trac.wordpress.org/ticket/5590 #5590] - /wp-includes/l10n.php - Jacob Santos # [http://trac.wordpress.org/ticket/5621 #5621] - /wp-includes/locale.php - Jacob Santos # [http://trac.wordpress.org/ticket/5509 #5509] - /wp-includes/pluggable.php - Updated by Jacob Santos based on Robert Deaton's patch from [http://trac.wordpress.org/ticket/2477 #2477] # [http://trac.wordpress.org/ticket/3852 #3852] - /wp-includes/plugin.php - Martin Sturm and cleanup by Jacob Santos ([http://trac.wordpress.org/ticket/5225 #5225]) # [http://trac.wordpress.org/ticket/4383 #4383] - /wp-includes/registration.php - Robin Adrianse and cleanup by Jacob Santos # [http://trac.wordpress.org/ticket/5572 #5572] - /wp-includes/registration-functions.php - Jacob Santos # [http://trac.wordpress.org/ticket/4742 #4742] - /wp-includes/taxonomy.php - Jacob Santos # [http://trac.wordpress.org/ticket/5513 #5513] - /wp-includes/template-loader.php - Jacob Santos # [http://trac.wordpress.org/ticket/5233 #5233] - /wp-includes/update.php - Jacob Santos # [http://trac.wordpress.org/ticket/5572 #5572] - /wp-includes/vars.php - Jacob Santos # [http://trac.wordpress.org/ticket/5572 #5572] - /wp-includes/version.php - Jacob Santos # [http://trac.wordpress.org/ticket/2474 #2474] - /wp-includes/wpdb.php - Robert Deaton ===Incomplete Files=== Every file should be labeled as a work in progress and if you want to adopt a file or function for documentation, then do so and add it to this list. These files however have already been started and could use some help with completion. # [http://trac.wordpress.org/ticket/5632 #5632] - /wp-includes/capabilities.php - Started by Jacob Santos # [http://trac.wordpress.org/ticket/5633 #5633] - /wp-includes/category.php - Started by Jacob Santos # [http://trac.wordpress.org/ticket/5634 #5634] - /wp-includes/category-template.php - Started by Jacob Santos # [http://trac.wordpress.org/ticket/5635 #5635] - /wp-includes/classes.php - Started by Jacob Santos # [http://trac.wordpress.org/ticket/5637 #5637] - /wp-includes/cron.php - Started by Jacob Santos # [http://trac.wordpress.org/ticket/5578 #5578] - /wp-includes/comment.php - Updated by Jacob Santos based on Peter Walker's patch from [http://trac.wordpress.org/ticket/2648 #2648] # [http://trac.wordpress.org/ticket/5636 #5636] - /wp-includes/feed.php - Started by Jacob Santos # [http://trac.wordpress.org/ticket/5638 #5638] - /wp-includes/formatting.php - Started by Jacob Santos # [http://trac.wordpress.org/ticket/5639 #5639] - /wp-includes/functions.php - Started by Jacob Santos # [http://trac.wordpress.org/ticket/5640 #5640] - /wp-includes/general-template.php - Started by Jacob Santos # [http://trac.wordpress.org/ticket/5642 #5642] - /wp-includes/link-template.php - Started by Jacob Santos # [http://trac.wordpress.org/ticket/3982 #3982] - /wp-includes/post.php - Started by Scott Merrill, updated by Jacob Santos and based in part off of [http://trac.wordpress.org/ticket/2473 #2473]. # [http://trac.wordpress.org/ticket/0000 #0000] - /wp-includes/post-template.php - Started by You # [http://trac.wordpress.org/ticket/0000 #0000] - /wp-includes/query.php - Started by You # [http://trac.wordpress.org/ticket/0000 #0000] - /wp-includes/script-loader.php - Started by You # [http://trac.wordpress.org/ticket/0000 #0000] - /wp-includes/theme.php - Started by You # [http://trac.wordpress.org/ticket/5512 #5512] - /wp-includes/user.php - Started by Jacob Santos # [http://trac.wordpress.org/ticket/0000 #0000] - /wp-includes/widgets.php - Started by You This ticket is outdated because admin-functions.php is no longer used for functions and is deprecated in 2.5+. The documentation is still good for the functions that were moved to the wp-admin/includes/*.* folder. * [http://trac.wordpress.org/ticket/3970 #3970] - /wp-admin/admin-functions.php - Started by Sabin Iacob
摘要:
请注意,您对站长百科的所有贡献都可能被其他贡献者编辑,修改或删除。如果您不希望您的文字被任意修改和再散布,请不要提交。
您同时也要向我们保证您所提交的内容是您自己所作,或得自一个不受版权保护或相似自由的来源(参阅
Wordpress-mediawiki:版权
的细节)。
未经许可,请勿提交受版权保护的作品!
取消
编辑帮助
(在新窗口中打开)
本页使用的模板:
模板:WordPress导航
(
查看源代码
)(受保护)