API reference: user-generated documentation proposal

General Discussion
#1

Hi everybody!

As you all know to successfully understand and use Panda it is important to first go through the Manual and eventually use it in parallel with the API reference pages. Short of going through the source code (certainly an instructive possibility in many circumstances) Manual and API reference should help with most of a developer’s needs.

One problem I’m noticing however is that the automatically generated documentation for classes and methods relies of course on the developer appropriately documenting the source code. Even if this has been done properly the descriptions cannot be further expanded by third-party developers who might be able to clarify concepts, add usage examples and share knowledge obtained through precious hands-on experience.

Conceptually it might appear that as the API pages are automatically overwritten with every new release of Panda there wouldn’t be much of a point in allowing user-generated documentation in them: it would get deleted when the next version is released! And technically it might appear difficult if not impossible to limit the third-party editing only to the user-generated portions of the text, while keeping the automatically generated sections locked.

In practice, and given the current setup, it is technically feasible and is not particularly difficult in MediaWiki to do so while guaranteeing persistence of the user-generated documentation across releases.

The key is in the use of Mediawiki’s templates to transclude (including) in one page the content of another. In this context an API reference page would contain the automatically generated content plus, for every class and method, transcluding templates such as {{ugd:aClass::aMethod}}, i.e.:

<b>aClass</b>
from pandac.PandaModules import aClass

Class : aClass
Description : <automatically generated documentation>
User generated documentation:
{{ugd:aClass}}

aMethod
Description: <automatically generated documentation>
User generated documentation:
{{ugd:aClass::aMethod}}

This would include in the otherwise static and locked reference page the content of the user-editable pages “aClass” and “aClass::aMethod” from the “ugd” (user-generated documentation) namespace.

As the current documentation is version-unaware with each new release the templates in the newly generated documentation page would conveniently reference the already existing user-generated documentation page for a given class or method. If we then wanted to switch to a system where the API reference for multiple releases are kept online at the same time all that would be needed is for the version number to be included in the page names, and for a mediawiki bot to copy the content of, say, page “ugd:1.6.2/aClass::aMethod” to page “ugd:1.6.3/aClass::aMethod”.

In general this is part of the solution to a problem I’m seeing in the forum, where a lot of interesting knowledge is accumulating in the discussion threads, often about specific classes and methods, but doesn’t find its way in the documentation where it belongs, and where it would prevent the same issues from being raised over and over again. Needless to say this would especially ease the support burden on Panda’s developers that could then spend more of their precious time doing what they probably like to do most: expand and strengthen Panda and of course deal with their own games.

What do you guys think?

Manu

#2

Hmm, why not just submit appropriate patches to the code when you want to make a change to the API documentation? That’s easy to do, it doesn’t require building any new systems, and it has the advantage that the comments in the code itself are also maintained as current and instructive.

We’re always happy to accept patches. :slight_smile:

David

#3

Your suggestion requires for -everybody- who wants to expand the API documentation to:

  1. get the source code and familiarise him/herself with it
  2. potentially deal with C++ when they’d rather stick to python
  3. compile the C++ file to make sure their change didn’t do any damage before checking it in (yes, even if the change is supposed to be only in a comment - one never knows a semi-colon could have gone missing!)
  4. become familiar with CVS to deal with the check-in procedures
  5. wait until the next release for the expanded documentation to be published for the benefit of all.

All these things certainly do not hurt, BUT: my suggestion requires -one person- to do -few-, -minimal- changes to the tool that export the in-code documentation to mediawiki (I’m assuming you batch-import mediawiki’s input xml format?) while everybody else only needs to know how to write in plain English and, if they wish to, in wikitext.

So, the why is very simple: your suggestion is more work for everybody, my suggestion is less work for everybody except the one person that has to implement it. :wink:

If I had access to your tools I’d offer to do it myself, I’ve done very similar things for a large-ish visual effects company no longer than 18 months ago. But an internal person, knowing the current setup, would literally breeze through it.

#4

Well, that was an exaggeration. You only need to know that in C++ comment lines start with //.
Plus, if you just give me a couple of text lines and say which text line belongs to which method, I’d be happy to check those in, too. :slight_smile:

#5

FINE THEN! I shall be mortally resentful for the next 5 seconds :angry: and then forgive you both. :wink:

…5 seconds later…

Ok, done. You have been forgiven. 8)

Too bad though. I do stumble upon many descriptions that are incomplete, not particularly clear or simply have some typos here and there and it seems to me having to check-in a new version of the source code for this purpose is like shooting a fly with a naval cannon. Never mind. We shall endure! :smiley:

#6

Well, we could create such a system that allows people to add their descriptions, and I see how that can be useful, but I’m afraid such a tool would be hard to maintain.
It would be better if someone grabbed a cvs checkout, took an afternoon to add a couple of comments, hit a “cvs diff > comments.patch” and emailed that patch to us (we’d then make sure it still compiles).

But actually, I wanted to get away from our own tool that generates the API ref, and use pydoc instead.