Wouldn't architectural designs showing class relationships be more pressing than going through and commenting every single function with that format? What's the biggest problem people are complaining about? Is it that they don't understand that int GetIDTarget() const; is a method that gets the id of the target as an integer? Or could it be that they don't understand how classes interact and what things exist on the server and what on the client and how those classes all tie together or inheret to create all the elements of the game?
If you are going to create a remotely useful guide it seems like you're attacking the problem in very much the wrong way. The proposal of creating a fully commented version of the SDK is not only a huge amount of pointless coding, exhausting to maintain properly but also a missunderstanding of the difficulties. If the original topic is still the topic at hand then it's acquanting them with architecture and an easy to understand layout of how the classes work rather than pedantic descriptions of specific methods that you would want to create. I'd suggest tackling the theory of how Source is implemented before wasting your time describing hundreds of self explaniatory methods without any insight into how it's tied together. For example with the GetIDTarget, it's an example of client side maintained information that is later used by the HUD to create a user name display and by player class to manipulate the head angles so it appears to look at someone. Something like that is far more usefull, but on the same token you wouldn't put that into the code itself you'd have it kept in an external documentation or somewhere. On Thu, Jan 15, 2009 at 5:53 PM, Steve Henderson < steven.j.hender...@gmail.com> wrote: > Yes this is a good idea -- but how do we distribute it without > violating Valve's Source SDK agreement (which says we can only > redistro OBJ files)? > > It seems to me that we'd need them to agree to let us release just the > commented functions and classes > (without the underlying source code view as is exported by default > with doxygen). > > Then as mentioned earlier, we could identify priority classes and > split up the work using > a version controlled MOD. Then export only the classes and function > documentation. > > But Valve would have to be OK with this. > > It would also be interesting if this documentation project could be > distributed/viewed through the Steam > client...I'm not a big steam fan, and would rather use my own > browser...but this might allow > for access to the documentation for licensed users only > > Steve > > > > > > On Thu, Jan 15, 2009 at 1:41 AM, James Luzwick <jluzw...@gmail.com> wrote: > > I figured the basic idea is to create block comments above each function > and > > class javadoc style. This would allow whomever is doing the > documentation > > to use doxygen ( > > http://www.stack.nl/~dimitri/doxygen/<http://www.stack.nl/%7Edimitri/doxygen/>). > > > > For example, take this function from c_hl2mp_player.cpp (OB HL2 > Multiplayer > > Code) > > > > /** > > * This returns the Player's ID Target > > * > > * @param If I had any parameters I would describe them here. > > * > > * @return The ID Target as an int. > > */ > > int C_HL2MP_Player::GetIDTarget() const > > { > > return m_iIDEntIndex; > > } > > > > The doxygen tool would then parse the file and discover this > documentation > > for the function and export it to a nicely formatted HTML page. > > > > The Apache guys commonly use this (well a lot of people use this) an > example > > of what it would look like, is this: > > > > Apache Xerces XML C++ Library ( > > http://xerces.apache.org/xerces-c/apiDocs-3/classes.html ) > > > > On Wed, Jan 14, 2009 at 9:06 PM, Walter Gray <chrysal...@gmail.com> > wrote: > > > >> Well, I hope it will be moot when the next version comes out, but right > >> now I was thinking we could do both, and tag the version specific > >> parts. I just started a new mod, and was forced to go with EP1 for > >> shader support. I'd like to move away from it, but for now there are > >> valid reasons for using either version, so I figure both versions should > >> be supported. I think the key thing here is to turn it into a more > >> widespread community effort, which is what wikis are good for. > >> If you're working on a project, you add to the sections relevant to > >> what you're working on, or volunteer some time when you have it. I may > >> not have too much time free for the latter, but I plan to do plenty of > >> the former. I'm trying to teach my teammates how to use Source so I > >> figure if I'm going to be writing up notes, the least I can do is try > >> and make them easily accessible. I imagine that kind of thing is why > >> Valve stuck the documentation on a publicly editable wiki in the first > >> place. > >> I suspect the biggest roadblock right now is figuring out formatting > >> and getting the basic framework in place so people have some kind of > >> guideline to add to. Nobody seems to like setting up the architecture, > >> but once it's there and easy to add to, I expect people frequently > >> will. If someone would like to work with me on this or could offer some > >> suggestions, please email me. I'm trying to do it myself, but I'd > >> really appreciate any assistance. > >> > >> Steve Henderson wrote: > >> > Keeping the dream alive, here's another fundamental question -- > >> > should our efforts focus on EP1 or OrangeBox? > >> > > >> > On Wed, Jan 14, 2009 at 11:10 PM, Nick <xnicho...@gmail.com> wrote: > >> > > >> >> James is right. Nobody here is whining. We are discussing things that > >> >> must be done to help all current and future developers of the source > >> >> engine. > >> >> > >> >> If Valve refuses to recognize the need for more proper documentation, > >> >> and more open tools, then I am willing to investigate other more > >> >> documented, more open, and more widely used engines. Others have > >> >> privately emailed me with more drastic actions, but I for one believe > >> >> Valve will help us and not ignore us like they usually do. > >> >> > >> >> On Wed, Jan 14, 2009 at 8:56 PM, James Luzwick <jluzw...@gmail.com> > >> wrote: > >> >> > >> >>> I don't think any of us are "whining", I call it "discussing". I'm > >> sure > >> >>> everyone here "reads" the "tutorials" and uses what Valve has given > us > >> >>> graciously to it's full extent. We were merely talking about ways > of > >> >>> expanding VDC to contain more "documentation". I don't think anyone > of > >> us > >> >>> is going to devote all of their resources to figuring out exactly > what > >> the > >> >>> code does along with building the associated documentation. > Although, > >> I'm > >> >>> sure people will chip in just like they have with the "tutorials". > >> >>> > >> >>> On Wed, Jan 14, 2009 at 6:02 PM, Marshall <psycha...@hotmail.com> > >> wrote: > >> >>> > >> >>> > >> >>>> Ok as much as a whole DB of source code would be nice, you guys are > >> >>>> spending > >> >>>> more time whining about not having the code, when in that time you > >> could > >> >>>> have gone to the VDC, looked up a tut, then checked the steam > forums, > >> then > >> >>>> gone into your code, CNTRL+F ( a magical thing ) and :O!! You've > got > >> >>>> yourself some code. Ive only used the VDC steam forums, and tuts > and > >> Im > >> >>>> still a hella noob, but shit I get stuff done by just raping tuts > and > >> >>>> taking > >> >>>> parts I need. Something I do is any code I find that's handy I > take > >> and > >> >>>> stick into a notepad doc so if I need at again I just take a > gander. > >> So > >> >>>> meh. > >> >>>> > >> >>>> -------------------------------------------------- > >> >>>> From: "Tony Sergi" <to...@valvesoftware.com> > >> >>>> Sent: Wednesday, January 14, 2009 5:37 PM > >> >>>> To: "Discussion of Half-Life Programming" < > >> hlcoders@list.valvesoftware.com > >> >>>> > >> >>>> Subject: Re: [hlcoders] Technical Design Document or Quick > Reference > >> Guide? > >> >>>> > >> >>>> > >> >>>>> Well I started a particle tutorial, but I haven't had time to > finish > >> it, > >> >>>>> and I think there's enough info about them now anyway. Granted, > >> that's > >> >>>>> > >> >>>> not > >> >>>> > >> >>>>> strictly programming but it would have had some programming in it. > >> >>>>> -Tony > >> >>>>> > >> >>>>> > >> >>>>> -----Original Message----- > >> >>>>> From: hlcoders-boun...@list.valvesoftware.com > >> >>>>> [mailto:hlcoders-boun...@list.valvesoftware.com] On Behalf Of > John > >> >>>>> Standish > >> >>>>> Sent: January-14-09 7:30 PM > >> >>>>> To: Discussion of Half-Life Programming > >> >>>>> Subject: Re: [hlcoders] Technical Design Document or Quick > Reference > >> >>>>> Guide? > >> >>>>> > >> >>>>> I wonder if this is any thoughts on putting more tutorials up on > the > >> >>>>> > >> >>>> wiki? > >> >>>> > >> >>>>> On Wed, Jan 14, 2009 at 4:20 PM, Tony Sergi < > to...@valvesoftware.com > >> > > >> >>>>> wrote: > >> >>>>> > >> >>>>> > >> >>>>>> Some tutorials purposely didn't compile though ;) > >> >>>>>> I always hated copy and paste ones, and I've even made some in > the > >> past, > >> >>>>>> sadly. > >> >>>>>> -Tony > >> >>>>>> > >> >>>>> _______________________________________________ > >> >>>>> To unsubscribe, edit your list preferences, or view the list > >> archives, > >> >>>>> please visit: > >> >>>>> http://list.valvesoftware.com/mailman/listinfo/hlcoders > >> >>>>> > >> >>>>> > >> >>>>> > >> >>>> _______________________________________________ > >> >>>> To unsubscribe, edit your list preferences, or view the list > archives, > >> >>>> please visit: > >> >>>> http://list.valvesoftware.com/mailman/listinfo/hlcoders > >> >>>> > >> >>>> > >> >>>> > >> >>> _______________________________________________ > >> >>> To unsubscribe, edit your list preferences, or view the list > archives, > >> please visit: > >> >>> http://list.valvesoftware.com/mailman/listinfo/hlcoders > >> >>> > >> >>> > >> >>> > >> >> _______________________________________________ > >> >> To unsubscribe, edit your list preferences, or view the list > archives, > >> please visit: > >> >> http://list.valvesoftware.com/mailman/listinfo/hlcoders > >> >> > >> >> > >> >> > >> > > >> > _______________________________________________ > >> > To unsubscribe, edit your list preferences, or view the list archives, > >> please visit: > >> > http://list.valvesoftware.com/mailman/listinfo/hlcoders > >> > > >> > > >> > >> > >> _______________________________________________ > >> To unsubscribe, edit your list preferences, or view the list archives, > >> please visit: > >> http://list.valvesoftware.com/mailman/listinfo/hlcoders > >> > >> > > _______________________________________________ > > To unsubscribe, edit your list preferences, or view the list archives, > please visit: > > http://list.valvesoftware.com/mailman/listinfo/hlcoders > > > > > > _______________________________________________ > To unsubscribe, edit your list preferences, or view the list archives, > please visit: > http://list.valvesoftware.com/mailman/listinfo/hlcoders > > _______________________________________________ To unsubscribe, edit your list preferences, or view the list archives, please visit: http://list.valvesoftware.com/mailman/listinfo/hlcoders
