Doc generation problems

[GoogleCodeExporter]

Doc generation with -v reports:

$ tools/gendoc.sh -v
+--------------------------------------------------------------------------
| File /home/richard/src/pyglet.googlecode.com/trunk/pyglet/image/
| __init__.py, in pyglet.image.Texture.image_data
|   Warning: Invalid context for 'param'
|   Warning: 'type' did not expect an argument
|   Warning: Invalid context for u'rtype'
|
Warning: Failed identifier crossreference targets:
         - BasePlatform.create_configs
               (from pyglet.gl.Config)
         - Context.switch_to
               (from pyglet.gl.get_current_context)
         - Window.flip
               (from pyglet.window)
         - Window.set_mouse_exclusive
               (from pyglet.window)
         - Window.switch_to
               (from pyglet.window)
         - WindowEventHandler
               (from pyglet.window.event)
         - WindowFactory.get_matching_configs
               (from pyglet.gl.Config)
         - switch_to
               (from pyglet.window.Window)
         - texture
               (from pyglet.window.ImageMouseCursor.__init__)

Also there's some issues parsing function parameters in some docstrings. No
errors appear to be reported, but there's information missing in the
resultant API docs. See the pyglet.clock module for a good example.
Clock.get_fps has its return type documented in the summary table but
Clock.get_fps_limit does not.

Original issue reported on code.google.com by r1chardj0n3s on 11 Jun 2007 at 10:10

[GoogleCodeExporter]

Also pyglet.projection module docstring hasn't been rest'ed.

Original comment by r1chardj0n3s on 11 Jun 2007 at 10:19

[GoogleCodeExporter]

pyglet.projection was removed a long time ago, remember to clear out your 
.pyc's.

Original comment by Alex.Hol...@gmail.com on 12 Jun 2007 at 12:33

[GoogleCodeExporter]

Here's the output from a more recent build - most of the warnings seem to be
references to API bits which don't exist (eg. Context.switch_to refers to 
either the
Mac, Windows or Linux windows). I can remove them if that'll be productive.

I'm not sure what's causing the initial warnings, eg:

| File /home/anthony/pyglet/pyglet/pyglet/__init__.py, line 73, in 
pyglet.options
|   Warning: Line 80: Unknown target name: "pyglet".

===

+-------------------------------------------------------------------------------
------------
| File /home/anthony/pyglet/pyglet/pyglet/__init__.py, line 77, in 
pyglet.options
|   Warning: Line 84: Unknown target name: "pyglet".
|   
+-------------------------------------------------------------------------------
------------
| File /home/anthony/pyglet/pyglet/pyglet/image/__init__.py, in 
| pyglet.image.Texture.image_data
|   Warning: Invalid context for 'param'
|   Warning: 'type' did not expect an argument
|   Warning: Invalid context for u'rtype'
|   
Warning: Failed identifier crossreference targets:
         - BasePlatform.create_configs
               (from pyglet.gl.Config)
         - Context.switch_to
               (from pyglet.gl.get_current_context)
         - StaticSound
               (from pyglet.media)
         - Window.flip
               (from pyglet.window)
         - Window.switch_to
               (from pyglet.window)
         - WindowEventHandler
               (from pyglet.window.event)
         - WindowFactory.get_matching_configs
               (from pyglet.gl.Config)
         - dispatch_events
               (from pyglet.event.EventDispatcher.dispatch_event)
         - source
               (from pyglet.media.StaticMemorySource.__init__)
         - switch_to
               (from pyglet.window.Window)
               (from pyglet.window.Window.__init__)
               (from pyglet.window.Window.clear)
         - texture
               (from pyglet.media)
               (from pyglet.window.ImageMouseCursor.__init__)
         - video_format
               (from pyglet.media)
         - x
               (from pyglet.font.Text.halign)
         - y
               (from pyglet.font.Text.valign)

Editing the source code doesn't seem to actually change them, other than the 
line
numbers. I think I need to be pointed at some docs or clued in on what's 
happening
there (I've already tried reinstalling and removing .pyc files).

Original comment by anthony....@gmail.com on 26 Oct 2007 at 12:41

[GoogleCodeExporter]

Thanks for the update, all warnings fixed in r1338.  

Most of the warnings were due to missing abstract methods (e.g. in the Window 
base class), out of date 
docstrings (some of the Window and media methods were renamed since docstrings 
were first written), or 
subtleties with how epydoc finds docstrings (in two cases the error was caused 
by a superclass's docstring being 
inherited into a method with different parameters).

Original comment by Alex.Hol...@gmail.com on 27 Oct 2007 at 1:21

• Changed state: Fixed