misc doc edits
authorCampbell Barton <ideasman42@gmail.com>
Sat, 5 Nov 2011 01:48:10 +0000 (01:48 +0000)
committerCampbell Barton <ideasman42@gmail.com>
Sat, 5 Nov 2011 01:48:10 +0000 (01:48 +0000)
- remove recently added sphinx reference workaround.
- tested doxygen, correct some warnings, set tab width and added pymathutils group.
- added convenience target 'make doc_doxy'

27 files changed:
GNUmakefile
doc/doxygen/Doxyfile
doc/doxygen/doxygen.source
doc/python_api/sphinx_doc_gen.py
intern/audaspace/intern/AUD_C-API.h
intern/ghost/intern/GHOST_Buttons.h
intern/ghost/intern/GHOST_DisplayManager.h
intern/ghost/intern/GHOST_EventWheel.h
source/blender/editors/curve/editcurve.c
source/blender/editors/include/ED_view3d.h
source/blender/imbuf/intern/moviecache.c
source/blender/python/mathutils/mathutils.c
source/blender/python/mathutils/mathutils.h
source/blender/python/mathutils/mathutils_Color.c
source/blender/python/mathutils/mathutils_Color.h
source/blender/python/mathutils/mathutils_Euler.c
source/blender/python/mathutils/mathutils_Euler.h
source/blender/python/mathutils/mathutils_Matrix.c
source/blender/python/mathutils/mathutils_Matrix.h
source/blender/python/mathutils/mathutils_Quaternion.c
source/blender/python/mathutils/mathutils_Quaternion.h
source/blender/python/mathutils/mathutils_Vector.c
source/blender/python/mathutils/mathutils_Vector.h
source/blender/python/mathutils/mathutils_geometry.c
source/blender/python/mathutils/mathutils_geometry.h
source/blender/render/intern/source/external_engine.c
source/gameengine/Ketsji/KX_KetsjiEngine.h

index b06344ca238b4aacdb58ab4caefce1d2dc498327..f6a6ee91f3123e3a75e64af332c1fc2307e15c2e 100644 (file)
@@ -151,6 +151,7 @@ help:
        @echo ""
        @echo "Documentation Targets (not assosiated with building blender)"
        @echo "  * doc_py   - generate sphinx python api docs"
+       @echo "  * doc_doxy - generate doxygen C/C++ docs"
        @echo "  * doc_dna  - generate blender file format reference"
        @echo "  * doc_man  - generate manpage"
        @echo ""
@@ -238,9 +239,13 @@ check_sparse:
 # Simple version of ./doc/python_api/sphinx_doc_gen.sh with no PDF generation.
 doc_py:
        $(BUILD_DIR)/bin/blender --background -noaudio --factory-startup --python doc/python_api/sphinx_doc_gen.py
-       cd doc/python_api ; sphinx-build -n -b html sphinx-in sphinx-out
+       cd doc/python_api ; sphinx-build -b html sphinx-in sphinx-out
        @echo "docs written into: '$(BLENDER_DIR)/doc/python_api/sphinx-out/contents.html'"
 
+doc_doxy:
+       cd doc/doxygen; doxygen 
+       @echo "docs written into: '$(BLENDER_DIR)/doc/doxygen/html/index.html'"
+
 doc_dna:
        $(BUILD_DIR)/bin/blender --background -noaudio --factory-startup --python doc/blender_file_format/BlendFileDnaExporter_25.py
        @echo "docs written into: '$(BLENDER_DIR)/doc/blender_file_format/dna.html'"
index b4d3b14b9dde48f8a74fa959b561a6af76a4dadb..dd112ed6a48b503721329abf3a20ed1bee1c2261 100644 (file)
@@ -193,7 +193,7 @@ SEPARATE_MEMBER_PAGES  = NO
 # The TAB_SIZE tag can be used to set the number of spaces in a tab. 
 # Doxygen uses this value to replace tabs by spaces in code fragments.
 
-TAB_SIZE               = 8
+TAB_SIZE               = 4
 
 # This tag can be used to specify a number of aliases that acts 
 # as commands in the documentation. An alias has the form "name=value". 
index 375234d26a3c53f531271cfd4fbaf19946d6a103..cc3a2b14a924f121c59a89ec2638e4ab2cf7a69c 100644 (file)
  *  \ingroup python
  */
 
+/** \defgroup pymathutils Python Mathutils
+ *  \ingroup python
+ */
+
 /** \defgroup pythonintern Python RNA and Operators
  *  \ingroup python
  */
index 3c43b5bc4dab1ef3195ed5404c5f57644bb2eb65..36e092f85b7e11effd9e5167edd09d74d8a892fd 100644 (file)
@@ -150,10 +150,6 @@ def is_struct_seq(value):
     return isinstance(value, tuple) and type(tuple) != tuple and hasattr(value, "n_fields")
 
 
-def module_id_as_ref(name):
-    return "mod_" + name.replace(".", "__")
-
-
 def undocumented_message(module_name, type_name, identifier):
     if str(type_name).startswith('<module'):
         preloadtitle = '%s.%s' % (module_name, identifier)
@@ -391,10 +387,6 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
 
     write_title(fw, "%s (%s)" % (title, module_name), "=")
 
-    # write reference, annoying since we should be able to direct reference the
-    # modules but we cant always!
-    fw(".. _%s:\n\n" % module_id_as_ref(module_name))
-
     fw(".. module:: %s\n\n" % module_name)
 
     if module.__doc__:
@@ -453,20 +445,19 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
         if type(descr) == MemberDescriptorType:
             if descr.__doc__:
                 value = getattr(module, key, None)
+
                 value_type = type(value)
                 descr_sorted.append((key, descr, value, type(value)))
     # sort by the valye type
     descr_sorted.sort(key=lambda descr_data: str(descr_data[3]))
     for key, descr, value, value_type in descr_sorted:
-        type_name = value_type.__name__
-        py_descr2sphinx("", fw, descr, module_name, type_name, key)
 
+        # must be documented as a submodule
         if is_struct_seq(value):
-            # ack, cant use typical reference because we double up once here
-            # and one fort he module!
-            full_name = "%s.%s" % (module_name, type_name)
-            fw("   :ref:`%s submodule details <%s>`\n\n\n" % (full_name, module_id_as_ref(full_name)))
-            del full_name
+            continue
+
+        type_name = value_type.__name__
+        py_descr2sphinx("", fw, descr, module_name, type_name, key)
 
         attribute_set.add(key)
 
index c7b8cb777714ed3646364c940ba61567a921a492..2b7c94bcc5bcf0d83411946365c360fdf05b9c33 100644 (file)
@@ -454,7 +454,7 @@ extern float* AUD_readSoundBuffer(const char* filename, float low, float high,
 /**
  * Pauses a playing sound after a specific amount of time.
  * \param handle The handle to the sound.
- * \param time The time in seconds.
+ * \param seconds The time in seconds.
  * \return The silence handle.
  */
 extern AUD_Handle* AUD_pauseAfter(AUD_Handle* handle, float seconds);
index 7a3d8b6ae71c0d97c125f5d3b76ad553d4451497..0209dc304e41c27a19c76abec8b3d4a654b7452a 100644 (file)
@@ -52,15 +52,15 @@ struct GHOST_Buttons {
 
        /**
         * Returns the state of a single button.
-        * @param mask. Key button to return.
+        * @param mask Key button to return.
         * @return The state of the button (pressed == true).
         */
        virtual bool get(GHOST_TButtonMask mask) const;
 
        /**
         * Updates the state of a single button.
-        * @param mask. Button state to update.
-        * @param down. The new state of the button.
+        * @param mask Button state to update.
+        * @param down The new state of the button.
         */
        virtual void set(GHOST_TButtonMask mask, bool down);
 
index 8329d7be94eff9174c6c2316f2aa45f10dc70085..d7a9b151d14f455fc2ca1c35f4dffa81200a979b 100644 (file)
@@ -72,7 +72,7 @@ public:
        /**
         * Returns the number of display settings for this display device.
         * @param display The index of the display to query with 0 <= display < getNumDisplays().
-        * @param setting The number of settings of the display device with this index.
+        * @param numSettings The number of settings of the display device with this index.
         * @return Indication of success.
         */
        virtual GHOST_TSuccess getNumDisplaySettings(GHOST_TUns8 display, GHOST_TInt32& numSettings) const;
index 0036fa60275554a69afc5e8f1b5ff3b816840791..2a82ab8a630de86f521c3557e628d44b7227b11a 100644 (file)
@@ -26,7 +26,7 @@
  */
 
 /** \file ghost/intern/GHOST_EventWheel.h
- *  \ingroup GHOSTeel.h
+ *  \ingroup GHOST
  * Declaration of GHOST_EventWheel class.
  */
 
index 4087002598e1e98ae8a28963ad35fbbd16cf6400..4a12206d4044ea95cb8b95e21569d188e9a7c981 100644 (file)
@@ -2812,12 +2812,7 @@ void CURVE_OT_select_inverse(wmOperatorType *ot)
 /** Divide the line segments associated with the currently selected
  * curve nodes (Bezier or NURB). If there are no valid segment
  * selections within the current selection, nothing happens.
- *
- * @deffunc subdividenurb subdivideNurb(void)
- * @return Nothing
- * @param  None
-*/
-
+ */
 static void subdividenurb(Object *obedit, int number_cuts)
 {
        Curve *cu= obedit->data;
index f69abb0996a351d9b71cd20badb1c1ed3ff909ff..e43ad964c9c13f9425d8bf25bbc62902f29261b9 100644 (file)
@@ -130,7 +130,6 @@ void ED_view3d_win_to_segment_clip(struct ARegion *ar, struct View3D *v3d, const
  * In orthographic view the resulting ray_normal will match the view vector.
  * @param ar The region (used for the window width and height).
  * @param v3d The 3d viewport (used for near clipping value).
- * @param out The resulting normalized world-space direction vector.
  * @param mval The area relative 2d location (such as event->mval, converted into float[2]).
  * @param ray_start The world-space starting point of the segment.
  * @param ray_normal The normalized world-space direction of towards mval.
@@ -140,7 +139,7 @@ void ED_view3d_win_to_ray(struct ARegion *ar, struct View3D *v3d, const float mv
 /**
  * Calculate a normalized 3d direction vector from the viewpoint towards a global location.
  * In orthographic view the resulting vector will match the view vector.
- * @param ar The region (used for the window width and height).
+ * @param rv3d The region (used for the window width and height).
  * @param coord The world-space location.
  * @param vec The resulting normalized vector.
  */
@@ -171,6 +170,7 @@ void ED_view3d_from_m4(float mat[][4], float ofs[3], float quat[4], float *dist)
  * @param ofs The view offset to be set, normally from RegionView3D.ofs.
  * @param quat The view rotation to be set, quaternion normally from RegionView3D.viewquat.
  * @param dist The view distance from ofs to be set, normally from RegionView3D.dist.
+ * @param lens The view lens angle set for cameras and lamps, normally from View3D.lens.
  */
 void ED_view3d_from_object(struct Object *ob, float ofs[3], float quat[4], float *dist, float *lens);
 
index 1d752fe9c6d9b7f53b26c6b7fea291cc02706289..41169a1c211eb936063e339fb5d7c7bd2c89247b 100644 (file)
@@ -25,7 +25,7 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/** \file blender/blenkernel/intern/moviecache.c
+/** \file blender/imbuf/intern/moviecache.c
  *  \ingroup bke
  */
 
index 770a743b733b1ac318e1b12f91dfdc3d7d674fbc..41c1568dbde4cca1bded4daacd1b54592339c79c 100644 (file)
@@ -25,8 +25,8 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/** \file blender/python/generic/mathutils.c
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils.c
+ *  \ingroup pymathutils
  */
 
 #include <Python.h>
index bcea62c8f1c84360b370fd1ca0e7461cf2f0032c..70b0ef93ebde508af45b46eae9623e696010cc12 100644 (file)
@@ -26,8 +26,8 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/** \file blender/python/generic/mathutils.h
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils.h
+ *  \ingroup pymathutils
  */
 
 //Include this file for access to vector, quat, matrix, euler, etc...
index a0035e5f34dbc24d1197285c6794bfd62b6efdc1..c374d0eb73de99d0dad2c4a8804793ca89e00104 100644 (file)
@@ -21,8 +21,8 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/** \file blender/python/generic/mathutils_Color.c
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils_Color.c
+ *  \ingroup pymathutils
  */
 
 
index 231fab511c8be62ad0490a5d43a7c92e2d9fd175..6c84b5f596dec93c224b8252cd19818551e04453 100644 (file)
@@ -27,8 +27,8 @@
  *
  */
 
-/** \file blender/python/generic/mathutils_Color.h
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils_Color.h
+ *  \ingroup pymathutils
  */
 
 
index 4d44ec8b1e95818c75e2a1f5f6ebbd678444c537..ce9ac5fbbb51dd3449c1d530f0506f53bf737614 100644 (file)
@@ -25,8 +25,8 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/** \file blender/python/generic/mathutils_Euler.c
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils_Euler.c
+ *  \ingroup pymathutils
  */
 
 
index 0c51a2a1dd84c2cc75399033bdb247e2bc0f576e..46f5910f31f51dd2c982edddd17dcff7a8288151 100644 (file)
@@ -27,8 +27,8 @@
  *
  */
 
-/** \file blender/python/generic/mathutils_Euler.h
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils_Euler.h
+ *  \ingroup pymathutils
  */
 
 
index 2a5d45bdff0a12c3a1e7ae3b6dff5727666e9f63..980dbd17a9693aea2474e82c8fe5e7e547e64bc3 100644 (file)
@@ -24,8 +24,8 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/** \file blender/python/generic/mathutils_Matrix.c
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils_Matrix.c
+ *  \ingroup pymathutils
  */
 
 
index 01fae91b1a465f5c46d87e5effec8c4ac2e913a9..275f4270787990624bfe648068cc50de32fa20bf 100644 (file)
@@ -26,8 +26,8 @@
  *
  */
 
-/** \file blender/python/generic/mathutils_Matrix.h
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils_Matrix.h
+ *  \ingroup pymathutils
  */
 
 
index f892c25f67eed395b05ab9249c62873a443e9389..3f0a5d55ec2db6a0cfdea053e1b7b0763e3918af 100644 (file)
@@ -24,8 +24,8 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/** \file blender/python/generic/mathutils_Quaternion.c
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils_Quaternion.c
+ *  \ingroup pymathutils
  */
 
 
index c8029d616799a7892ff3833d5bbd0c272dd58f4f..13060ed9ff93aaefaab45382a0e0b55fd6274be9 100644 (file)
@@ -27,8 +27,8 @@
  *
  */
 
-/** \file blender/python/generic/mathutils_Quaternion.h
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils_Quaternion.h
+ *  \ingroup pymathutils
  */
 
 
index a932d8d6b01e2314f2a9a444b366c674cb16deda..ba7cf604c422e983e5eb4433b30f3d4caa50a283 100644 (file)
@@ -24,8 +24,8 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/** \file blender/python/generic/mathutils_Vector.c
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils_Vector.c
+ *  \ingroup pymathutils
  */
 
 
index bd4cd5f5be7d900df8a5b5c83b71fbf53dd27baa..610805fcee03f103fa090f710dc0f359fbd5ed59 100644 (file)
@@ -27,8 +27,8 @@
  *
  */
 
-/** \file blender/python/generic/mathutils_Vector.h
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils_Vector.h
+ *  \ingroup pymathutils
  */
 
 
index 6e8624721b7f948b346f2b15be04842e90f1dc2d..e8721a3a91dc9907ae87ffb3cfeda72dc6c28043 100644 (file)
@@ -26,8 +26,8 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/** \file blender/python/generic/mathutils_geometry.c
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils_geometry.c
+ *  \ingroup pymathutils
  */
 
 
index 58a2bf9142ffa068f3c6913261cea3e0885baedc..1b339bdaf006c99489f4698d583bbe9f0a20bf66 100644 (file)
@@ -26,8 +26,8 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/** \file blender/python/generic/mathutils_geometry.h
- *  \ingroup pygen
+/** \file blender/python/mathutils/mathutils_geometry.h
+ *  \ingroup pymathutils
  */
 
 /*Include this file for access to vector, quat, matrix, euler, etc...*/
index b37da67f743c0f6ab9ffaed7a1f64ac77e36af5a..b7f89e260a8518ae1071482f29d926708702c710 100644 (file)
@@ -26,7 +26,7 @@
  * ***** END GPL LICENSE BLOCK *****
  */
 
-/** \file blender/render/intern/pipeline/engine.c
+/** \file blender/render/intern/source/external_engine.c
  *  \ingroup render
  */
 
index 40f157ef0a46fc07da843da5897e6e5da9d2dfca..5a02da07e4324ffdccd9ba62b1601ec893f4d41f 100644 (file)
@@ -387,8 +387,7 @@ public:
        void SetUseOverrideFrameColor(bool overrideFrameColor);
 
        /** 
-        * Enables/disables the use of the framing bar color of the Blender file's scenes.
-        * @param useSceneFrameColor The new setting.
+        * Check if the frame color is being overridden.
         */
        bool GetUseOverrideFrameColor(void) const;