Steve makes a good point. Items such as those require a much more formal math background to understand. I'll be the first to admit I taught myself the math I need to know for operations in 3d space, I do not have a formal background what so ever. I think documenting items such as that would help out most of us with a less formal background. Now that is not to say one could not figure them out via googling, but would you rather waste 1 hour googling and trying to understand what a Quaternion is or just having a summary telling you what it does. I'd vote for the latter.
I also agree though that documenting accessors would be a waste of time, if not silly. The name itself for an accessor describes what it does. On Thu, Jan 15, 2009 at 10:29 AM, Steve Henderson < steven.j.hender...@gmail.com> wrote: > 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/> > <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 > > _______________________________________________ To unsubscribe, edit your list preferences, or view the list archives, please visit: http://list.valvesoftware.com/mailman/listinfo/hlcoders
