   Recommended methods for documenting your game code
  I've been feeling curious about something the past few days. How do you all document the game engines/code that you design, and to what extent? Do you prefer to write all your documentation by hand? Do you rely on auto-documenting tools like Doyxgen? Are normal comments in your code enough for you? Or do you use some combination of the above? How detailed do you make your documentation? Is it just a list of function calls and effects for the users of your API to know, or do you actually get into the technical details of what's running behind the scenes? I was hoping to get some real-experience answers to these questions, and a good discussion going on the most important question of all: what do you consider a well-documented game/engine?My team and I have been working quite a bit on documenting our game engine (which we wrote from scratch), so maybe we can use some of that as a launch board. Here are some pieces of documentation from my game engine, and their intended audience.Developer's Quick Start GuideThis document is intended to get the reader quickly up-to-speed with the major concepts and foundation behind our game's engine, and introduce them to how to use the engine to do basic things like drawing pictures, text, playing audio, or loading data from script files.Allacrost Code StandardI think everyone's gotta have one of these. [smile] This is intended mainly for developers on the staff, and outsiders who wish for their code to get accepted into the main source tree.Allacrost Video Engine DocumentationA work-in-progress document describing how to use every implemented feature in our video engine, complete with pictures and even a flash animation. [wink]Allacrost Technical DocumentationDoxygen-generated reference to our entire code base, including the map editor (some sections of code still need to be documented fully). This is of a code snapshot about 5 days ago, which is already now out-of-date since I re-designed the entire audio engine and commited it this morning. [lol] Doxygen generated a whopping 1,476 files in creating this document!!This discussion is not meant to be about our documentation in particular, but I thought it would be good to share something real. If you take the time to actually go through some of that documentation, do you consider those pieces to be great, good, adequate, lacking, or unacceptable? What's missing or needs to be removed?I hope that people just don't ignore this thread since it has no technical discussion. But remember that writing the code is half the work, and explaining it so others can use and understand it is the other half. [wink]   
  hey Roots,At a glance, I would say that your documentation is fantastic! I just skimmed through the video engine documentation and found it easier to read and understand than the windows sdk docs and the directx sdk docs. I understand too that they have much more in them and it is more low level stuff but the english that you've used makes it much more understandable in my opinion! [wink]Now for my input:I think documentation should provide a variety of things:In-Code1. A simple, plain explanation of what functions/variables do/are for.2. An outline of what each parameter of a function is intended for.3. What return values on functions are and how they are found/possible values.4. Comments at key sections of functions to describe what is happening.Documentation/Help Files1. Same as last pt.1.2. The prototype for functions.3. Same as last pt.2.4. An easy to understand explanation of the types of situations you would use the function/variable for and some remarks on any out-of-the-ordinary things that go with using them (like if a function fails or reaches the end of a search unsuccessfully).5. Examples! Examples are (IMO) one of the easiest ways to see how a function works. They provide proper working code for someone to use as a reference any time they need it, and if the description of the function is nearby (eg. on the same page...) then its even easier to understand the workings of the function.6. Tutorials! Tutorials are another great way to show common uses for functions and how to go about setting up commonly used objects within the program. If the documentation is for an editor, tutorials are the best you can do IMO. They show exactly how to use the editor and carry out the tasks you want it to and expect it to.I personally have only done the In-Code stuff at the moment for my engine but once I finish it, I will certainly be trying to have the Documentation/Help Files section covered too as my engine is very much geared towards ease of use, rather than giving you too much control and too many options (more than needed I mean). This simplifies the coding process by a long way but obviously makes the engine more complex and therefore the documentation also more complex and full. The main reason I want to complete this documentation very thoroughly is because I want to give others the oportunity to use my engine in the future if they want. I think this is another important factor in how thorough your documentation is. If others are expected to be using your engine, they need to know it as well as you do - therefore, document thoroughly. However, if it is definately intended only for you, then In-Code comments and documentation should suffice (since you wrote the engine, you know what's happening).So to answer your original questions: I like to use informative comments In-Code (sometimes 10+ lines for a single function if it has many parameters) and I would like to have a very detailed and example-full help file as a reference for newcomers to the engine and experienced users alike (I know I like to go throught the docs searching for functions I don't know of in hopes of finding one that does what I want).Hope that helps get the discussion going [smile],   ;  I agree that examples/tutorials are the best ways to teach how to use a piece of code. In fact, I was going to add to the quick start guide a section that creates a game mode implementation from scratch, using everything that is taught in that guide. Then I think I'll consider that piece of documentation complete. [smile]Typically we do the majority of commenting in our header files (all the doxygen commenting is here). In the source files, we don't use doxygen comments, but do use regular comments to explain what pieces of code are doing. Here's an example header file and source file for the data and scripting component of our game engine.Header FileSource FileYou can see that the header file comments are incredibly verbose (probably more comments than actual code), while the source file is sparsely (but IMO, adequately) commented.   ;Quote:Original post by RootsTypically we do the majority of commenting in our header files (all the doxygen commenting is here). In the source files, we don't use doxygen comments, but do use regular comments to explain what pieces of code are doing. Here's an example header file and source file for the data and scripting component of our game engine.First off, I am most impressed by the amount of documentation you guys have =)  Especially going into detail how your systems work for someone unfamiliar with the architecture/codebase :)I would, however, (very) strongly suggest to use brief descriptions in headers, and detailed descriptions in the source files.  It serves two purposes:(1)  It serves as good (and detailed) documentation on the function you're currently looking at, without bouncing back and forth to the header.(2)  It nicely breaks up your functions visually, so you have an easier time navigating your code.Point (1) is the most important here, obviously.  Imo, the headers should serve as a "quick-glance" to a particular class, so that your programmers can quickly skim through it and pick out the code they need to deal with.  The actual source file should contain the detailed descriptions, where any caveats, parameters, design decisions, todos, and so on are listed.  This method of documentation also follows the whole declaration-definition/header-source paradigm.  Additionally, keeping your detailed documentation in the source file (instead of the header) will prevent insane recompiles whenever you update the detailed descriptions.  In worst case, you really do not want to recompile your entire engine just because you wanted to update the detailed descriptions in a header :)At my job we used to have minimal commenting (side-effect of insane deadlines imposed by publishers), but we've pushed hard to use Doxygen and have commented our code as I had suggested above: Briefs in headers, detailed in source.  It ridiculous the change it has made =)  It's so much easier navigating the code and researching how the systems work.Graf   ;  I definitely think having regular documentation + a "quick start" guide, and even tutorials is the best way to go for "non-code" documentation. With the video engine, I started out thinking I'd make it quick and dirty, just minimal explanation and some code samples, so people could find things quick. That didn't work for long :) If a function wasn't documented, there was no way to know it existed, and if I didn't write explanations for how things work, it was easy to have misunderstandings which lead to other people wasting time trying to figure it out, or bugs in some cases.As for documentation in headers... Personally I like to put detailed descriptions in the source code for each function, for the reasons Grafalgar said. So, I find the header-heavy doxygen approach a bit hard to maintain because a lot of documentation gets duplicated (duplication=bad, bad!). It also makes the header files really long and hard to wade through if you just want to get an idea of what functions a class provides. OTOH I think maybe it's a necessary evil... If you're writing an engine/library, I'm not sure how it works in Linux, but at least in Windows you only give the headers and lib/dll, not the source files themselves. So, it makes sense that you'd want headers to be heavily documented because that's all the public will see.   ;  Interesting point you have there. I can definitely see where you are coming from, and indeed I have thought the same way at times when I started seeing the header files explode with comments. But if you just want a "quick function list", well that's one of the things that the technical documentation generated by doxygen is supposed to do. Take a look. Now IMO, that's even easier/nicer to read than a cleaned header file. [wink]I'm not trying to say your way is wrong, I'm just pointing out that you can achieve the same effect you have with a clean header with the docs that are generated. At the engineering company in which I work, we place our doxygen comments in the header file as well. (In fact, several parts of our code standard are modeled after the standard I use at work). Source files area already pretty large and unwieldly with all the code, and if you add doxygen to that I think it would make it even harder to read through. Just my opinion though.   ;  The easiest code to document is code that doesn't exist:  Don't write code that won't be needed.The second easiest code to document is code that is so obvious that it hardly needs any documentation anyway:  Write your code so that it does the obvious thing - the thing that the user of the code will expect it to do anyway.Probably not at all useful, but I'm in the mood for little aphorisms.John B   ;  hey,i've just (well for the last week on and off...) been working on the documentation for my new engine. now i thought it appropriate to post this here (sorry to resurrect the dead [wink]!) since this topic was all about documentation. i would like you to check out the documentation i've down so far if you can spare downloading it...Luminaire Engine Documentationi'm quite an experienced delphi programmer and have no knowledge of standard help files so i've written the documentation into a program that mimics a help file, but i assume can do lots more if/when i get to putting the stuff in (like example pictures).anyway, i've taken basic descriptions from my source and then added many notes and explanations into the descriptions to (hopefully) make them clear and understandable to unfamiliar users to the engine. this is one reason i would like to ask if you could check it out - to see if there are any things you would change/improve on to make it better/easier to understand.i will be releasing the engine to the public once i get this documentation finished so the sooner i get problems reported/ideas, the sooner i can get it out for people to try (if they like).thanks in advance to those who take the time to look through it and tell me what you think!   