Too hard to documentation = lazy. Always document, always always. Especially when releasing something to the public. First thing I ever learned at work.
On Tue, Jan 13, 2009 at 2:59 PM, Nick <[email protected]> wrote: > Why the should we try to make documentation if even valve thinks its > too hard to do? > > On Tue, Jan 13, 2009 at 3:57 PM, James Luzwick <[email protected]> wrote: > > I'm not sure what you mean by this. There ton's of proprietary source > code > > on the valve developer wiki not to mention the source code is available > to > > anyone who has a half life 2 key. This wouldn't be sold either.. it > would > > just be more of a mod that can be worked on by public developers. > > > > On Tue, Jan 13, 2009 at 12:56 PM, Tobias Kammersgaard < > > [email protected]> wrote: > > > >> Distributing the sourcecode isn't allowed, this seems like a pretty big > >> problem. > >> > >> /ScarT > >> > >> > >> 2009/1/13 Steve Henderson <[email protected]> > >> > >> > And we could make a 3rd party GUI tool that allows for a rich diff > >> > like view between someone's MOD (MyMod) and the DokuMod. This would > >> > create a view of the code > >> > that would interweave the DokuMod inline documentation in with the > >> > user's Mod so they could see our documentation alongside theirs, and > >> > possibly selectively > >> > import the comments and changes they like... > >> > > >> > On Tue, Jan 13, 2009 at 1:01 PM, Steve Henderson > >> > <[email protected]> wrote: > >> > > We could create a special MOD (dokuMod) strictly for documentation. > >> > > > >> > > This would could have: > >> > > > >> > > - A plethora of doxygen friendly INLINE comments > >> > > > >> > > - Inline hyperlinks to more extensive documentation on @ the > >> > > developer.valve wiki > >> > > > >> > > - Default enabling the many built-in debug layers that Valve already > >> > > included. These would be enabled by default so someone playing a > the > >> > > dokuMod would see all the debug skins and such > >> > > > >> > > - Self documenting classes -- For example, custom PropClass that > have > >> > > skins and hovering sprites that serve as documentation > >> > > > >> > > - Custom VGUI classes that could show handy visualizations of the > >> > > scene graph, firing actions etc. > >> > > > >> > > - Included map that allow for walking through in FPS view and > >> > > observing all the debugging and other turorials > >> > > > >> > > The mod would create full, nightly doxygen html that has UML and the > >> > > inline documentation > >> > > > >> > > I'd be up to contribute.. > >> > > > >> > > Steve > >> > > > >> > > > >> > > > >> > > On Tue, Jan 13, 2009 at 12:53 PM, John Standish <[email protected]> > >> > wrote: > >> > >> I agree with Nuno on the fact that documentation is very important. > >> I've > >> > >> just started getting back in to the Source SDK and I am completely > >> lost > >> > at > >> > >> points. It's not the fact that I do not know C++ it's the fact I am > >> > trying > >> > >> to figure out every little piece of source and what points to what. > >> Sure > >> > the > >> > >> name conventions are helpful but some things are just either wonky > or > >> > >> convoluted. Documentation would help tremendously. I've used > Doxygen > >> to > >> > >> create documentation but that has only done so much. > >> > >> > >> > >> On Tue, Jan 13, 2009 at 9:45 AM, Nuno Silva < > >> > [email protected]>wrote: > >> > >> > >> > >>> I can't stress this enough, but documentation is *very* important > in > >> > large > >> > >>> projects such as Source, one shouldnt try to figure out what all > the > >> > code > >> > >>> does, considering how it's not even possible to do so since most > of > >> the > >> > >>> code > >> > >>> isnt even public. > >> > >>> > >> > >>> Documenting the code ourselves would be an interesting idea, > however > >> it > >> > is > >> > >>> a > >> > >>> long task, and as such should be very well organized. > >> > >>> > >> > >>> Since i dont use the Source SDK, i probably wont help, so good > luck > >> to > >> > >>> everyone. > >> > >>> > >> > >>> On Tue, Jan 13, 2009 at 5:31 PM, Willem Engel < > [email protected]> > >> > wrote: > >> > >>> > >> > >>> > Yes, time to put some sense back into this thing. Does anyone > know > >> of > >> > a > >> > >>> > system that would allow multiple persons to add comments to code > >> > without > >> > >>> > modifying the code itself? I imagine something like a wiki > based > >> on > >> > a > >> > >>> > class-diagram of the current code. We might even be able to add > it > >> to > >> > a > >> > >>> > section on the valve dev wiki? > >> > >>> > Commenting the code itself would require the lot of us to share > a > >> > >>> > subversioning system of some kind. > >> > >>> > > >> > >>> > ZuM wrote: > >> > >>> > > Good to see that someone on this list isn't flaming like some > >> > above. > >> > >>> > > > >> > >>> > > Now onto the topic, James, none that i know of is doing that. > >> > >>> > > > >> > >>> > > 2009/1/13 James Luzwick <[email protected]> > >> > >>> > > > >> > >>> > >> On the topic of design documents. Does anyone know if there > has > >> > been > >> > >>> a > >> > >>> > >> push > >> > >>> > >> by anyone in particular to create javadoc-like doxygen > comments > >> > for > >> > >>> all > >> > >>> > the > >> > >>> > >> code in the SDK? If there is some person in general working > on > >> > it, I > >> > >>> > would > >> > >>> > >> love to add to it as I program and figure out more about the > >> SDK. > >> > >>> > >> > >> > >>> > >> I think this would be a good idea as it could easily be > exported > >> > to > >> > >>> > HTML. > >> > >>> > >> _______________________________________________ > >> > >>> > >> 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
