Difference between revisions of "API Reference Project"
From Joomla! Documentation
m (Removed reference to old developer site as this is no longer available.) |
m (Hutchy68 moved page JDOC:API Reference Project to Archived:API Reference Project: Project is no longer valid) |
||
| (16 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
| − | The aim of the API Reference Project is to construct a useful reference manual on the Joomla 1.5 (and later) Framework API which will complement, rather than replace, the automatically generated material on http://api.joomla.org. The starting point for the API Reference is the [[Framework]] | + | __NOTOC__ |
| + | <noinclude>{{notice|This project is inactive and current closed until further notice. A new method is discussed for bringing an API Reference which may not be part of the Joomla! Documentation Wiki.}}</noinclude> | ||
| + | The aim of the API Reference Project is to construct a useful reference manual on the Joomla 1.5 (and later) Framework API which will complement, rather than replace, the automatically generated material on http://api.joomla.org. The starting point for the API Reference is the Framework page ([[API16:Framework|Joomla 1.6 Framework]] | [[API15:Framework|Joomla 1.5 Framework]]) which lists all of the classes in the Framework API. | ||
If you would like to help us with this massive project, then all you need to do is register on this wiki. You don't need to join a Working Group and you don't need to ask permission. You just register and get started. A good idea is to pick a class you know something about, or have spent time researching, and start there. Also feel free to add examples, improve explanations, or correct mistakes on existing pages. | If you would like to help us with this massive project, then all you need to do is register on this wiki. You don't need to join a Working Group and you don't need to ask permission. You just register and get started. A good idea is to pick a class you know something about, or have spent time researching, and start there. Also feel free to add examples, improve explanations, or correct mistakes on existing pages. | ||
| Line 8: | Line 10: | ||
==Guidance notes== | ==Guidance notes== | ||
| − | The starting page for the API Reference is the [[Framework]] | + | The starting page for the API Reference is the Framework page ([[API16:Framework|Joomla 1.6 Framework]] | [[API15:Framework|Joomla 1.5 Framework]]) where you can see a complete list of all the classes in the API. Each class will be given its own wiki page linked to from the Framework page. Each class page includes a list of all the public methods available and each of those methods will also have its own page (actually a "sub-page"). |
| − | + | To simplify the documentation process, the class and method pages have already been created automatically. We reduced the documentation process to three pieces of knowledge, only humans can provide: | |
| − | + | * The writing of a '''comprehensive description''' of the class | |
| + | * The collection of '''valuable links''' (further reading) for that class | ||
| + | * The provision of '''examples''' to put theory into practice | ||
Sources of information that might be useful when writing for the API Reference: | Sources of information that might be useful when writing for the API Reference: | ||
| Line 19: | Line 23: | ||
* It can also be useful to search http://forum.joomla.org for further information and examples. | * It can also be useful to search http://forum.joomla.org for further information and examples. | ||
| − | ===Class | + | ===Class/Method Descriptions=== |
| − | + | Each class and method need a comprehensive description, so novices understand the idea behind that class/method. Explain what it's used for. If you wish you can add information to the design pattern that this class represents, and the concept behind it. Find a balance between useful information and technical detail. Don't be too generic, but do not start to explain HOW the class/method actually does the work. If the user wants to know about that, he/she will look at the source body provided within the method page. | |
| − | + | In order to edit the description, click on the "Edit description" link on the top right of the page. | |
| − | |||
| − | + | ===See Also section of the Class/Method=== | |
| + | The See Also section collects valuable links the provide further reading to that class or method. Provide links to wiki tutorials or other resources of use that might help the user to fully understand the functionality of this class or method. | ||
| − | === | + | ===Code Examples/Comments=== |
| − | + | One very important resource for help novices understand and learn about the Framework are code examples and comments of experienced users. Show the user how the class/method is used. Start with an easy example, then go on and maybe solve a fictive problem with the help of that class/method. If you've just learned about the way a certain class or method works, this is the perfect time to spend 10 minutes of your time, and write down what you've just learned. It will save hundreds of fellow developers hours of their time and your work will be highly appreciated. | |
| − | [[Category: | + | |
| + | Adding a code example is very easy. Once you're logged into the wiki, you'll see a "Leave a comment..." link below the "Examples" heading of the class/method page. Click on it, and a form will pop up, where you can enter your comment or code example. | ||
| + | |||
| + | You can use every wiki markup, within your code examples. | ||
| + | |||
| + | If you want to include''' PHP code''' in your example, frame the code with '''<nowiki><source lang="php"> </source></nowiki>''' tags, so the code will be properly highlighted. | ||
| + | |||
| + | ==Notes on Joomla Versions== | ||
| + | Everything you create, will be there to help fellow Joomla Developers for a long time. We eliminated the problem of different documentations for different versions of Joomla. Once you contributed for a certain class or method of the Joomla Framework, your work will automatically be included into all versions of the Joomla Framework Reference that include that respective class or method. | ||
| + | |||
| + | '''An example:''' | ||
| + | You wrote a code example for the Joomla 1.5 Framework documentation of [[API15:JNode|JNode]]. Since the class JNode still exists in the Joomla 1.6 Framework ([[API16:JNode|JNode in 1.6]]), your code example will be displayed here as well. | ||
| + | |||
| + | '''What does this mean?''' | ||
| + | If you provide code, that is valid for one version of Joomla only (say for 1.6 but not for 1.5), please tell us that within your code example / description / see also link. | ||
| + | <noinclude> </noinclude> | ||
| + | |||
| + | [[Category:Archived version Joomla! 1.5]] | ||
Latest revision as of 11:36, 15 June 2013
This page has been archived. This page contains information for an unsupported Joomla! version or is no longer relevant. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.
This project is inactive and current closed until further notice. A new method is discussed for bringing an API Reference which may not be part of the Joomla! Documentation Wiki.
The aim of the API Reference Project is to construct a useful reference manual on the Joomla 1.5 (and later) Framework API which will complement, rather than replace, the automatically generated material on http://api.joomla.org. The starting point for the API Reference is the Framework page (Joomla 1.6 Framework | Joomla 1.5 Framework) which lists all of the classes in the Framework API.
If you would like to help us with this massive project, then all you need to do is register on this wiki. You don't need to join a Working Group and you don't need to ask permission. You just register and get started. A good idea is to pick a class you know something about, or have spent time researching, and start there. Also feel free to add examples, improve explanations, or correct mistakes on existing pages.
We are only documenting the classes in the /libraries/joomla directory. These are the Joomla Framework classes. Some of the material developed on the wiki API Reference will gradually be merged into the phpDocumentor tags in the source code itself and hence will end up on http://api.joomla.org too.
Our inspiration is the online reference manual for PHP. For example, see this page: http://www.php.net/manual/en/function.echo.php which can be accessed by a simple, clearly defined, standardised URL and which permits user comments to be added.
Guidance notes[edit]
The starting page for the API Reference is the Framework page (Joomla 1.6 Framework | Joomla 1.5 Framework) where you can see a complete list of all the classes in the API. Each class will be given its own wiki page linked to from the Framework page. Each class page includes a list of all the public methods available and each of those methods will also have its own page (actually a "sub-page").
To simplify the documentation process, the class and method pages have already been created automatically. We reduced the documentation process to three pieces of knowledge, only humans can provide:
- The writing of a comprehensive description of the class
- The collection of valuable links (further reading) for that class
- The provision of examples to put theory into practice
Sources of information that might be useful when writing for the API Reference:
- Current source code (of course). To find out how to get the latest source code, visit the Joomla! Developer Site.
- http://api.joomla.org.
- It can also be useful to search http://forum.joomla.org for further information and examples.
Class/Method Descriptions[edit]
Each class and method need a comprehensive description, so novices understand the idea behind that class/method. Explain what it's used for. If you wish you can add information to the design pattern that this class represents, and the concept behind it. Find a balance between useful information and technical detail. Don't be too generic, but do not start to explain HOW the class/method actually does the work. If the user wants to know about that, he/she will look at the source body provided within the method page.
In order to edit the description, click on the "Edit description" link on the top right of the page.
See Also section of the Class/Method[edit]
The See Also section collects valuable links the provide further reading to that class or method. Provide links to wiki tutorials or other resources of use that might help the user to fully understand the functionality of this class or method.
Code Examples/Comments[edit]
One very important resource for help novices understand and learn about the Framework are code examples and comments of experienced users. Show the user how the class/method is used. Start with an easy example, then go on and maybe solve a fictive problem with the help of that class/method. If you've just learned about the way a certain class or method works, this is the perfect time to spend 10 minutes of your time, and write down what you've just learned. It will save hundreds of fellow developers hours of their time and your work will be highly appreciated.
Adding a code example is very easy. Once you're logged into the wiki, you'll see a "Leave a comment..." link below the "Examples" heading of the class/method page. Click on it, and a form will pop up, where you can enter your comment or code example.
You can use every wiki markup, within your code examples.
If you want to include PHP code in your example, frame the code with <source lang="php"> </source> tags, so the code will be properly highlighted.
Notes on Joomla Versions[edit]
Everything you create, will be there to help fellow Joomla Developers for a long time. We eliminated the problem of different documentations for different versions of Joomla. Once you contributed for a certain class or method of the Joomla Framework, your work will automatically be included into all versions of the Joomla Framework Reference that include that respective class or method.
An example: You wrote a code example for the Joomla 1.5 Framework documentation of JNode. Since the class JNode still exists in the Joomla 1.6 Framework (JNode in 1.6), your code example will be displayed here as well.
What does this mean? If you provide code, that is valid for one version of Joomla only (say for 1.6 but not for 1.5), please tell us that within your code example / description / see also link.