Andrew, I agree we shouldn't waste time with self documenting accessors (getters/setters).
But here are a couple of counter examples that I had to figure out myself through wasteful trial and error AxisAngleQuaternion ConcatTransforms SetLocalTransform A lot of the 3D math functions are like this..they make sense to the authors, but are highly dependent on one's convention/education about various matrix operations and coordinate systems. Steve On Thu, Jan 15, 2009 at 1:09 PM, Andrew Ritchie <gotta...@gmail.com> wrote: > 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 > > _______________________________________________ To unsubscribe, edit your list preferences, or view the list archives, please visit: http://list.valvesoftware.com/mailman/listinfo/hlcoders
