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
