Good points there, a wiki plus comments with how-to-use examples (and a good "was this post helpful" kinda system) would be very usefull. Added bonus for doing it that way is google indexing of the documentation.
Gustavo Ramos Lira wrote: > You could make some sort of tool to extract the DocComments from the > commented files and store them is some format. Since the comments are > the property of those who type them, those can be freely distributed. > Then you just need the same tool to take the files and comment them on a > different project. > However, this could be complicated due to source code never staying > quite the same way. And even a small change could raise difficulties to > the use of that tool. So, I think having some sort of wiki would be a > lot more helpful. And I don't know if anyone is familiar with it, but I > quite like the way php.net has php documented. They have a page for > every function, and then users can submit examples/modifications/uses > for that function in a comment area. I've used it quite a bit and like > it allot. > Overall, I think having documentation pages is much more helpful than > having the source code commented for a variety of reasons: > -Independent docs which are updated regardless of what valve does to the > source code is more reliable. If they change the source, you don't loose > your docs. > -For a new user (or even someone who already has some experience) > looking for a specific file, to then read the comments (or worse, > reading the comments on them all to find what they need) is probably > going to be a painful process. If you're new to the SDK, you probably > don't know where things are and don't want to be looking for them all > over the place to then know how to use them. > -Keeping the docs independent from the source code is generally a good > policy imo. One less thing tied to the source code that you need to > maintain along with it. > -_Allot_ more easily distributed. > > Gustavo Lira > > Tobias Kammersgaard escreveu: >> 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
