mirror of
https://github.com/codeigniter4/CodeIgniter4.git
synced 2025-02-20 11:44:28 +08:00
Tweaking docs to show parent class methods.
This commit is contained in:
Lonnie Ezell
parent
eefaa3a98d
commit
1495fac9ad
BIN
user_guide_src/source/documentation/ELDocs.tmbundle.zip
Normal file
BIN
user_guide_src/source/documentation/ELDocs.tmbundle.zip
Normal file
Binary file not shown.
202
user_guide_src/source/documentation/index.rst
Normal file
202
user_guide_src/source/documentation/index.rst
Normal file
@ -0,0 +1,202 @@
|
||||
#################################
|
||||
Writing CodeIgniter Documentation
|
||||
#################################
|
||||
|
||||
CodeIgniter uses Sphinx to generate its documentation in a variety of formats,
|
||||
using reStructuredText to handle the formatting. If you are familiar with
|
||||
Markdown or Textile, you will quickly grasp reStructuredText. The focus is
|
||||
on readability and user friendliness.
|
||||
While they can be quite technical, we always write for humans!
|
||||
|
||||
A local table of contents should always be included, like the one below.
|
||||
It is created automatically by inserting the following:
|
||||
|
||||
::
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<div class="custom-index container"></div>
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<div class="custom-index container"></div>
|
||||
|
||||
The <div> that is inserted as raw HTML is a hook for the documentation's
|
||||
JavaScript to dynamically add links to any function and method definitions
|
||||
contained in the current page.
|
||||
|
||||
**************
|
||||
Tools Required
|
||||
**************
|
||||
|
||||
To see the rendered HTML, ePub, PDF, etc., you will need to install Sphinx
|
||||
along with the PHP domain extension for Sphinx. The underlying requirement
|
||||
is to have Python installed. Lastly, you will install the CI Lexer for
|
||||
Pygments, so that code blocks can be properly highlighted.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
easy_install "sphinx==1.2.3"
|
||||
easy_install sphinxcontrib-phpdomain
|
||||
|
||||
Then follow the directions in the README file in the :samp:`cilexer` folder
|
||||
inside the documentation repository to install the CI Lexer.
|
||||
|
||||
|
||||
|
||||
*****************************************
|
||||
Page and Section Headings and Subheadings
|
||||
*****************************************
|
||||
|
||||
Headings not only provide order and sections within a page, but they also
|
||||
are used to automatically build both the page and document table of contents.
|
||||
Headings are formed by using certain characters as underlines for a bit of
|
||||
text. Major headings, like page titles and section headings also use
|
||||
overlines. Other headings just use underlines, with the following hierarchy::
|
||||
|
||||
# with overline for page titles
|
||||
* with overline for major sections
|
||||
= for subsections
|
||||
- for subsubsections
|
||||
^ for subsubsubsections
|
||||
" for subsubsubsubsections (!)
|
||||
|
||||
The :download:`TextMate ELDocs Bundle <./ELDocs.tmbundle.zip>` can help you
|
||||
create these with the following tab triggers::
|
||||
|
||||
title->
|
||||
|
||||
##########
|
||||
Page Title
|
||||
##########
|
||||
|
||||
sec->
|
||||
|
||||
*************
|
||||
Major Section
|
||||
*************
|
||||
|
||||
sub->
|
||||
|
||||
Subsection
|
||||
==========
|
||||
|
||||
sss->
|
||||
|
||||
SubSubSection
|
||||
-------------
|
||||
|
||||
ssss->
|
||||
|
||||
SubSubSubSection
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
sssss->
|
||||
|
||||
SubSubSubSubSection (!)
|
||||
"""""""""""""""""""""""
|
||||
|
||||
|
||||
|
||||
|
||||
********************
|
||||
Method Documentation
|
||||
********************
|
||||
|
||||
When documenting class methods for third party developers, Sphinx provides
|
||||
directives to assist and keep things simple.
|
||||
For example, consider the following ReST:
|
||||
|
||||
.. code-block:: rst
|
||||
|
||||
.. php:class:: Some_class
|
||||
|
||||
.. php:method:: some_method ( $foo [, $bar [, $bat]])
|
||||
|
||||
This function will perform some action. The ``$bar`` array must contain
|
||||
a something and something else, and along with ``$bat`` is an optional
|
||||
parameter.
|
||||
|
||||
:param int $foo: the foo id to do something in
|
||||
:param mixed $bar: A data array that must contain a something and something else
|
||||
:param bool $bat: whether or not to do something
|
||||
:returns: FALSE on failure, TRUE if successful
|
||||
:rtype: bool
|
||||
|
||||
::
|
||||
|
||||
$this->load->library('some_class');
|
||||
|
||||
$bar = array(
|
||||
'something' => 'Here is this parameter!',
|
||||
'something_else' => 42
|
||||
);
|
||||
|
||||
$bat = $this->some_class->should_do_something();
|
||||
|
||||
if ($this->some_class->some_method(4, $bar, $bat) === FALSE)
|
||||
{
|
||||
show_error('An Error Occurred Doing Some Method');
|
||||
}
|
||||
|
||||
.. note:: Here is something that you should be aware of when using some_method().
|
||||
For real.
|
||||
|
||||
See also :meth:`Some_class::should_do_something`
|
||||
|
||||
|
||||
.. php:method:: should_do_something()
|
||||
|
||||
:returns: Whether or not something should be done
|
||||
:rtype: bool
|
||||
|
||||
|
||||
It creates the following display:
|
||||
|
||||
.. php:class:: Some_class
|
||||
|
||||
|
||||
.. php:method:: some_method ( $foo [, $bar [, $bat]])
|
||||
|
||||
This function will perform some action. The ``$bar`` array must contain
|
||||
a something and something else, and along with ``$bat`` is an optional
|
||||
parameter.
|
||||
|
||||
:param int $foo: the foo id to do something in
|
||||
:param mixed $bar: A data array that must contain a something and something else
|
||||
:param bool $bat: whether or not to do something
|
||||
:returns: FALSE on failure, TRUE if successful
|
||||
:rtype: bool
|
||||
|
||||
::
|
||||
|
||||
$this->load->library('some_class');
|
||||
|
||||
$bar = array(
|
||||
'something' => 'Here is this parameter!',
|
||||
'something_else' => 42
|
||||
);
|
||||
|
||||
$bat = $this->some_class->should_do_something();
|
||||
|
||||
if ($this->some_class->some_method(4, $bar, $bat) === FALSE)
|
||||
{
|
||||
show_error('An Error Occurred Doing Some Method');
|
||||
}
|
||||
|
||||
.. note:: Here is something that you should be aware of when using some_method().
|
||||
For real.
|
||||
|
||||
See also :meth:`Some_class::should_do_something`
|
||||
|
||||
|
||||
.. php:method:: should_do_something()
|
||||
|
||||
:returns: Whether or not something should be done
|
||||
:rtype: bool
|
||||
@ -120,6 +120,30 @@ Class Reference
|
||||
.. note:: In addition to the methods listed here, this class inherits the methods from the
|
||||
:doc:`Request Class </libraries/request>` and the :doc:`Message Class </libraries/message>`.
|
||||
|
||||
The methods provided by the parent classes that are available are:
|
||||
|
||||
* :meth:`CodeIgniter\\HTTP\\Request::ipAddress`
|
||||
* :meth:`CodeIgniter\\HTTP\\Request::validIP`
|
||||
* :meth:`CodeIgniter\\HTTP\\Request::method`
|
||||
* :meth:`CodeIgniter\\HTTP\\Request::server`
|
||||
* :meth:`CodeIgniter\\HTTP\\Request::server`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::body`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::setBody`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::populateHeaders`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::headers`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::header`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::headerLine`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::setHeader`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::removeHeader`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::appendHeader`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::protocolVersion`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::setProtocolVersion`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::negotiateMedia`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::negotiateCharset`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::negotiateEncoding`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::negotiateLanguage`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::negotiateLanguage`
|
||||
|
||||
.. php:class:: CodeIgniter\\HTTP\\IncomingRequest
|
||||
|
||||
.. php:method:: isCLI()
|
||||
|
||||
@ -64,6 +64,25 @@ Class Reference
|
||||
.. note:: In addition to the methods listed here, this class inherits the methods from the
|
||||
:doc:`Message Class </libraries/message>`.
|
||||
|
||||
The methods provided by the parent class that are available are:
|
||||
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::body`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::setBody`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::populateHeaders`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::headers`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::header`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::headerLine`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::setHeader`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::removeHeader`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::appendHeader`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::protocolVersion`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::setProtocolVersion`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::negotiateMedia`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::negotiateCharset`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::negotiateEncoding`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::negotiateLanguage`
|
||||
* :meth:`CodeIgniter\\HTTP\\Message::negotiateLanguage`
|
||||
|
||||
.. php:class:: CodeIgniter\\HTTP\\Response
|
||||
|
||||
.. php:method:: statusCode()
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user