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
