1=======================
2Coding style for PyObjC 
3=======================
4
5:authors: Ronald Oussoren,
6          Bill Bumgarner
7:contact: pyobjc-dev@lists.sourceforge.net
8:URL: http://pyobjc.sourceforge.net/
9:copyright: 2002 The PyObjC Project
10
11Introduction
12------------
13
14This document describes the coding style for PyObjC.  Please use this style for
15new code and try apply this style to existing code while working on it.
16
17The management summary: 4-space indents in Python code, 1-TAB indents in C
18code.
19
20Python code
21-----------
22
23The coding style for core Python is used (see `PEP 8`_).  For consistency with
24Cocoa we use mixed-case identifiers (like ``lookUpClass``).
25
26PyObjC extensions to Apple frameworks should be clearly marked as such, 
27preferably by prefixing names with ``PyObjC`` or ``pyobjc``.  This should make
28it clear to users where they should look for documentation of an item: The
29Apple documentation or ours.
30
31.. _`PEP 8`: http://www.python.org/peps/pep-0008.txt
32
33C code
34------
35
36The coding style for core Python is used (see `PEP 7`_).  We use ``PyObjC`` 
37instead of ``Py`` as the prefix for globally visible symbols.
38
39All (Objective-)C files in ``Modules/objc/`` should include ``"pyobjc.h"`` as
40their first include.  The (Objective-)C files in the wrappers for frameworks
41should include ``"pyobjc-api.h"`` and should not use other headers files from
42``pyobjc-core``.
43
44The ``setup.py`` for a framework wrapper should defer most work to 
45``pyobjc_setup.py``, like so:
46
47.. code-block:: python
48
49   from pyobjc_setup import setup
50
51   setup(
52      name='pyobjc-framework-AddressBook',
53      version="2.3"
54      description = "Wrappers for the framework AddressBook on Mac OS X",
55      packages = [ "AddressBook" ],
56      install_requires = [
57          'pyobjc-core>=2.3b1',
58          'pyobjc-framework-Cocoa>=2.3b1',
59      ],
60   )
61
62The framework wrappers do *not* include a copy of ``pyobjc-api.h``, but 
63dynamicly fetches that at build time.
64
65Documentation
66-------------
67
68All items exported by the objc module and all PyObjC extensions to Apple
69frameworks (the AppKit and Foundation modules) should be documented using
70docstrings.
71
72All documentation-- both standalone documents and docstrings-- should be
73marked up using reStructuredText_ [ReST].
74
75ReST in DocStrings
76++++++++++++++++++
77
78reStructuredText_ can be used in doc strings.   ReST in DocStrings works
79exactly like a standalone ReST document, but the ReST is broken up slightly
80differently.
81
82To format the DocStrings to be ReST compatible, make the following
83changes/additions to the source.  These examples were taken from source found
84in the DocUtils source tree. 
85
86(1) Add appropriate ReST style fields to the top of the document as comments::
87
88        # Author: David Goodger
89        # Contact: goodger@users.sourceforge.net
90        # Copyright: This module has been placed in the public domain.
91
92(2) Add a module level variable that indicates that ReST is used to format
93    the text contained in the docstrings::
94
95        __docformat__ = 'reStructuredText'
96    
97(3) Format all other DocStrings as one normally would in Python.   Use ReST
98    style markup where appropriate.   For example, bulleted lists and
99    sections might commonly appear in the module or class docstrings.   The
100    docstrings for individual methods may use example blocks, hyperlinks, or
101    any other ReST markup.
102        
103.. _reStructuredText: http://docutils.sourceforge.net/rst.html
104
105.. _`PEP 7`: http://www.python.org/peps/pep-0007.txt
106