Difference between revisions of "API"
(Adds API Sandbox links) |
(adds local resources) |
||
| (8 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
| − | + | API documentation for software like mediawiki, drupal and web services. Both API documentation and API tools. OS and Internet API references. | |
| − | [[wp:ApplicationProgrammingInterface|Application Programming Interface]] ([[wp: | + | [[wp:ApplicationProgrammingInterface|Application Programming Interface]] ([[wp:API]]) is the information about the exposed or 'public' variables, methods and objects or classes that a system makes available to the developer who wishes to enhance the system or interface with the system programmaticly. Documenting the API is a critical software development function. Publishing those documents makes the 'API Docs' available for easy reference. Sometimes called Developer Docs, they are often used not just as a reference material, but also as a faster way to get familiar with a codebase than by reading the full source code itself. |
| − | == | + | == Best Practices == |
| − | + | Having good API/Developer documentation is a "Best Practice" that has several important positive effects. For adoption (meaning success) of your software, good API docs are essential. Actual experience in using the phpDocumentor tool, PyDoc, or other documentation tools is a quality that separates developers from non-developers or senior developers from jr. developers. Writing (good) (formatted) comments into your source code so that API docs can be automatically generated on a nightly basis is not optional if you are really interested in your software being successful. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | == | + | == Tools / Generators == |
| − | + | phpDocumentor is the best documentation tool for PHP sources with inspiration from JavaDoc. | |
| − | + | The PyDoc tool is used to generate documentation on the language itself, and is also leveraged as a framework for developers of help systems and obviously used to document any classes, and methods of source code. | |
| − | + | See http://phpdoc.org/ and http://en.wikipedia.org/wiki/Javadoc | |
| − | + | == Documenting PHP Code == | |
| + | The main resource is the [http://www.phpdoc.org Project website], including tutorials and full Documentation. The system can be installed via the PEAR installer, but should not be setup in an Internet-facing environment. See the [[PhpDocumentor]] article for details on our installation and usage. | ||
| − | == | + | == Documenting other languages == |
| − | + | Aside from the Python-specific PyDoc, there are [http://www.xs4all.nl/~rfsber/Robo/robodoc.html ROBODoc] (Windows and Fink) and [http://www.stack.nl/~dimitri/doxygen Doxygen] tools which should prove to meet all needs. For doxygen, you can | |
| − | + | <source lang="bash"> | |
| − | + | sudo apt-get install doxygen-gui doxygen doxygen-doc | |
| + | </source> | ||
| − | == | + | == Programming APIs == |
| − | + | SWIG [[wp:Swig]] ([http://www.swig.org/exec.html Executive Summary]) helps application developers reveal an API. Several open source projects leverage SWIG, such as Subversion, wxPython and wxWindows. In turn, other developers can enhance these generic APIs to customize them for a particular programming language. For example Python developers can use [http://pysvn.tigris.org/docs/pysvn_prog_guide.html pySVN] while work is underway to expand the PHP interface. See more in the Subversion manual http://svnbook.red-bean.com/nightly/en/svn-book.html#svn.developer.usingapi | |
| − | == | + | == Resources == |
| − | + | * http://gotapi.com publishes several API references for everything from HTML and CSS to DocBook and Drupal. This organized list of API references also features fast, as-you-type search. | |
| + | * Some other documentation resources: | ||
| + | ** [http://svn.wikimedia.org/doc/ MediaWiki Doxygen docs] | ||
| + | ** http://api.kde.org/ APIs of the K Desktop Environment | ||
| + | ** http://doc.trolltech.com/ APIs of the Qt GUI Toolkit | ||
| − | + | == Local Resources == | |
| + | These tips may not be strictly "API" documents, but they do reveal man pages, howtos, and other help; plus programmatic interfaces. | ||
| + | * Create your own internal-use API Documentation by creating a symbolic link from /usr/share/docs to /var/www/docs | ||
| + | * info:/dir (type this into the location bar of Konqueror) browse the Info system. You can of course type "info" in your shell, but I find that browsing "info" through Konqueror is a lot nicer. | ||
| + | * man:/command (type this into the location bar of Konqueror) browse the Man system. You can of course type "man command" in your shell, but I find that browsing "manuals" through Konqueror is a lot nicer. | ||
[[Category:Applications]] | [[Category:Applications]] | ||
Revision as of 07:28, 4 November 2008
API documentation for software like mediawiki, drupal and web services. Both API documentation and API tools. OS and Internet API references.
Application Programming Interface (wp:API) is the information about the exposed or 'public' variables, methods and objects or classes that a system makes available to the developer who wishes to enhance the system or interface with the system programmaticly. Documenting the API is a critical software development function. Publishing those documents makes the 'API Docs' available for easy reference. Sometimes called Developer Docs, they are often used not just as a reference material, but also as a faster way to get familiar with a codebase than by reading the full source code itself.
Contents
Best Practices[edit | edit source]
Having good API/Developer documentation is a "Best Practice" that has several important positive effects. For adoption (meaning success) of your software, good API docs are essential. Actual experience in using the phpDocumentor tool, PyDoc, or other documentation tools is a quality that separates developers from non-developers or senior developers from jr. developers. Writing (good) (formatted) comments into your source code so that API docs can be automatically generated on a nightly basis is not optional if you are really interested in your software being successful.
Tools / Generators[edit | edit source]
phpDocumentor is the best documentation tool for PHP sources with inspiration from JavaDoc.
The PyDoc tool is used to generate documentation on the language itself, and is also leveraged as a framework for developers of help systems and obviously used to document any classes, and methods of source code.
See http://phpdoc.org/ and http://en.wikipedia.org/wiki/Javadoc
Documenting PHP Code[edit | edit source]
The main resource is the Project website, including tutorials and full Documentation. The system can be installed via the PEAR installer, but should not be setup in an Internet-facing environment. See the PhpDocumentor article for details on our installation and usage.
Documenting other languages[edit | edit source]
Aside from the Python-specific PyDoc, there are ROBODoc (Windows and Fink) and Doxygen tools which should prove to meet all needs. For doxygen, you can
sudo apt-get install doxygen-gui doxygen doxygen-doc
Programming APIs[edit | edit source]
SWIG wp:Swig (Executive Summary) helps application developers reveal an API. Several open source projects leverage SWIG, such as Subversion, wxPython and wxWindows. In turn, other developers can enhance these generic APIs to customize them for a particular programming language. For example Python developers can use pySVN while work is underway to expand the PHP interface. See more in the Subversion manual http://svnbook.red-bean.com/nightly/en/svn-book.html#svn.developer.usingapi
Resources[edit | edit source]
- http://gotapi.com publishes several API references for everything from HTML and CSS to DocBook and Drupal. This organized list of API references also features fast, as-you-type search.
- Some other documentation resources:
- MediaWiki Doxygen docs
- http://api.kde.org/ APIs of the K Desktop Environment
- http://doc.trolltech.com/ APIs of the Qt GUI Toolkit
Local Resources[edit | edit source]
These tips may not be strictly "API" documents, but they do reveal man pages, howtos, and other help; plus programmatic interfaces.
- Create your own internal-use API Documentation by creating a symbolic link from /usr/share/docs to /var/www/docs
- info:/dir (type this into the location bar of Konqueror) browse the Info system. You can of course type "info" in your shell, but I find that browsing "info" through Konqueror is a lot nicer.
- man:/command (type this into the location bar of Konqueror) browse the Man system. You can of course type "man command" in your shell, but I find that browsing "manuals" through Konqueror is a lot nicer.
