Streamlining Reference Improvements

General Discussion
1

First I want to say that the idea I present here would likely lead to a much better maintained reference in the future, but is also probably very difficult to implement, maybe impractically so.

As we all know (or should know), the reference is full of undocumented, poorly documented, and even wrongly or conflictingly documented things (I should report the wrong ones, which are rare, but I don’t). Basic things (Like NodePath.SetR) remain undocumented. Why? Because it is a pain to document them, and the people in a position to do so are spending their time doing much more valuable things (Like making panda actually worth documenting). Thus I propose a system that would make it easy for people to improve the documentation. Here is my idea:

As I understand it, the documentation is generated by looking into the source, and digging out various information, and optimally some descriptive text. If one were to simply turn the reference into a wiki, it would get out of sync with the source. To edit it, one must have a CVS account, edit the corresponding files, and commit the change. Then, once a new version is released, the reference may be updated to reflect the change. Please correct if I am wrong about how the current system works.

Suppose there was a reference site that was directly used the source. Qualified users could make a change, directly in the reference, and commit it, which would actually commit their change back to the documentation in the repository. Conflict resolution could be simple, if there is ever a conflict, simply inform the user, and let them refresh the doc (to get the new version) and remake their changes. The provided text should be checked issues, and properly escaped as necessary so it can’t break the actual code.

Implementing such a system would require (among other things) version control commands to be sent by the web server, so there would have to be quite a bit of scripting there to get it all to work. I’m not sure if it would be practical, but I know that if it were implemented, people like me would be a lot more inclined to work on the documentation.

I personally don’t have the required skills, or services (an appropriate server) to implement it, but maybe someone wants to give it a try?

Anyway, any thoughts about my idea? Could it work? Would it help?

Thanks
-Craig

2

the auto-documentation-generation was bugged for quite time causing many documented functions to show up as undocumented. thought it has been fixed up recently (hopefully).

3

So, you’re proposing a kind of gui wrapper around a system to make updates to the C++ code and then commit those changes with CVS.

It does sound difficult, of course. If we decided to that route, it could take a while to implement it. If we did have such a system in place, would you be willing to use it to add comments for the missing functions?

If so, then what about addressing our immediate needs, before that system is done? Would you be willing to use CVS today, to add comments to the missing functions directly into the source code?

If you would, then I’ll be happy to set you up with CVS access. If you wouldn’t, then why not?

David

4

Yes.

I would make some use of it. I honestly can’t say I would spend lots of time fixing all the confusing bits as, without good documentation, I often don’t actually know what many things do, but if it were easy to fix things, and fixes became accessible immediately (though only in the docs for the CVS version, which could be quite different in some cases), I would be inclined to fix errors and missing stuff when I found them.

Last time I looked through the source (to try and figure out how lookAt worked so I could make a double version of it) I could not find anything. I just took a few min and tried to find NodePath.SetR (which I have been asked about on the IRC more than once) in there, and I found some stuff, but I have no idea if it was the right stuff, or how to document it. I’m basically lost when it comes to piles of C++ code. I’m not even sure I found the actual code. Most of my C knowledge comes from CG and GLSL. Also, my skills with version control are pretty marginal. I run and use an SVN server that rarely gets a commit from someone other than me. If I were to really dig into the code and commit documentation changes, I would like to be able to know if I broke the code on accident, so then I would need to learn how to compile it (committing things that make it not compile is likely considered bad I imagine). It’s just a rather steep learning curve. I would like to be able to get in there and fix things eventually, but I, and many other casual python based users are simply unable and/or scared to mess with the engine source.

If we don’t reduce the learning curve for fixing documentation, at least a set of instructions on how to fix the reference entries would be nice.

It would probably be easier to make a tool that would generate help from a working copy of the repository (I assume the current tool can do this, but may not be too user friendly). It could ether basically provide line numbers and file names for all of the docs it finds, and places missing docs could go (enabled via setting when generating the reference), or it could provide some function for actually editing and adding them directly.

If this approach were taken, it would avoid having to do anything special version control or server wise, though the users would have to work with the repository (it’s probably good for them to learn how anyway). I’m not sure about the abilities of a local web site (as in the reference you just generated on your hard drive) to modify files, but I think a signed java applet could do so. Thus, it could still give an interactive web interface, and avoid having to look in the source files, but would not avoid having to directly use the repository. All in all, much easier that it currently is (at least a lower learning curve, and easier to verify your changes), but not quite as easy to use as my original proposal. (But much easier to implement)

Regardless of how such a tool worked, it might be a good idea to flag documentation created that way as it is likely to contain different kinds of errors (like being readable and friendly, but actually get important details wrong). Also some functionality to be sure the added documentation is properly all comments, devoid of random invisible characters (as happens when copying text from sources online like the forums or manual), and some ability to put URLs into the manual would be nice. Oh, and linking to other reference items should be easy. If simply using the reference, you will work your way from NodePath all the way down to vertex list formats without seeing any indication of the existence of the vertex writing/rewriting classes. This is annoying. More links (though not as useful when looking at the code itself) would really help the online reference.

It might be worth running a poll to see who would do what/how much with which systems. It is clearly not worth implementing anything unless it would help substantially.

5

I think the DjangoBook (djangobook.com/) style of documentation is both better and easier. This system can work on manual as well as the reference.

This is how it works:

1 Only few people are authors, they have all the commit access and know how to use it.
2 The rest can add comments pretty much to any paragraph.
3 The authors read the comments regularly and make changes then mark the comment as “solved.”

I think this system has many advantages over wiki style system.

1 Authors feel ownership of the page and are held responsible.
2 Authors are in control of the correctness and tone of things
3 The commenters don’t have to rewrite the paragraph but maybe ask a question, ask for clarification, or even better start min discussion.
4 The doc’s source can still be in version control system this thing just a bolt on.
5 Reduction of errors, as all “edits” will be reviewed by one other person.
6 Less spam because, who looks at comments?
7 It feels like a more natural tool of communication between “pros” and “newbs” unlike wiki which is more of a pear 2 pear thing.

I further see this system improved by adding different comment types such as:
1 Extra info comment - which basically adds clarification which Author does not want in main text and sticks around.
2 Spelling and grammar - comment which points out quality and should be quickly fixed by Author and then removed.
3 Question comment - can either be incorporated in the text (then removed) or answered with an “Extra info comment” and treated as such.
4 Discussion comment - mini dialog or full thread like topic.
5 Clarification comment - clarify the text, hopefully with a suggestion, then removed.

Other improvements can be a more stricter authorship. As in you sign on to be a “page author” then receive emails regarding comments and have your name appear on the page. If author is not taking care of comments the page becomes author-less and some one can claim it.

Make comments painless, not require sign in etc…

I actually started on a site like this for panda3d but it some how went south. Maybe i should finish it. ( treedoc.appspot.com/ )

6

Well, after some more digging, I managed to get the CVS downloaded (Possibly a link to the source forge project somewhere on the site would be nice. Perhaps a link to sourceforge.net/scm/?type=cvs&group_id=38909 from the downloads page would be good)

I actually found the appropriate code in there, and I think I understand how one would mess with the documentation text, at least for the methods with existing documentation. It seems like a pain to do though. I would just end up spending all my time finding the right place and getting the hard wrapping right. I could make something with a nice GUI to do the formatting pretty easily I guess. Then I would need to figure out how to extract all the documentation info to verify that I did everything right.

Anyway, Treeform presents an interesting idea.

If I get everything setup to properly modify the doc info, and get committing changes worked out (when I’m ready, I’ll want someone to walk me through so that I don’t do anything stupid, like upload all those .ds_store files, or break the something). Maybe under Treeform’s system I could potentially become an “author”.