Do we need documentation at this stage if so what kind?
Posted: Sun Sep 19, 2010 9:38 pm
I began really exploring the code base two days and I noticed that, obviously, it's pretty big, but that there was no documentation.
My prior coding experiences were with C/C++ projects that at the very basic level documented function prototypes in the header files, which was normally adequate. It would be nice to have documentation of namespaces, classes etc which give their usage, the file in which they are defined, extra comments etc.
I think we could also use some tutorials as documentation that do explain how fundamental things work, e.g. the things listed in the HACKING file.
Seeing as I'm new to the codebase I could add most of the documentation while simultaneously familiarizing myself with it, I'm new to C# though so I might get things wrong. Persons more familiar with the engine could add some tutorials, or I can do that when I read up a bit on it.
We also need to discuss what system we're gonna use for the documentation and what kind of nomenclature. The coding documentation should be in decent looking HTML, I guess.
My prior coding experiences were with C/C++ projects that at the very basic level documented function prototypes in the header files, which was normally adequate. It would be nice to have documentation of namespaces, classes etc which give their usage, the file in which they are defined, extra comments etc.
I think we could also use some tutorials as documentation that do explain how fundamental things work, e.g. the things listed in the HACKING file.
Seeing as I'm new to the codebase I could add most of the documentation while simultaneously familiarizing myself with it, I'm new to C# though so I might get things wrong. Persons more familiar with the engine could add some tutorials, or I can do that when I read up a bit on it.
We also need to discuss what system we're gonna use for the documentation and what kind of nomenclature. The coding documentation should be in decent looking HTML, I guess.