Better Documentation for the Code

[Alcon]

Is there a project out there currently to create some better documentation for the phpBB3 code? The documentation that exists right now is pretty weak. It's full of holes and stubs and the in code comments are pretty much as minimal as it gets. It'd be a huge help to mod developers if someone could tackle the project of filling the code with better comments and then writing up some real, thorough documentation that covers every nook and cranny of the code.

I'd be willing to tackle the project, except I have to actually learn the code first, I'm pretty unfamiliar with it aside from templating and writing very superficial mods. Can anyone do this? Is there already a project underway somewhere to do this? If not I can try and tackle it, but I'll have to post lots of questions on exactly what various functions and features do.

[Alcon]

Would people be interested in a project like this? Or perhaps I should ask, would people like to see this done?

[Highway of Life]

Hi Alcon,

Please be a bit patient, your request is being discussed/considered.

Thanks.

[Acyd Burn]

To get no false impression... this is not discussed by the developers. What you talk about is modifying code and not documenting it. Therefore, i am out of it again...

And he clearly asked for people who would be interested in it or would help him.

[Highway of Life]

If I understood his request (and I think I have), he’s asking who would be interested in expanding and building a more thorough documentation of classes, functions and every bit of code in phpBB3 so that it may be more easily understood by MOD Authors and coders who have to work with the phpBB3 Framework.

One thing I forgot to mention, the Olympus Wiki: http://olympuswiki.naderman.de was built for the purpose of expanding on the code documentation.
I think you’ll find quite a bit of documentation you may be after there, and it would be a great avenue to contribute documentation to as you go through the code.

[Prince of area51]

Just my 2 cents: I think a documentation wiki should be set up at phpBB.com so that any of the Team Members can update/add to the documentation at ease. This way all the work will be divided and any one from the team can work on it

[Acyd Burn]

The user documentation will never be within a wiki (this is not wanted and will also not work - comments yes, but not wiki). To the contrary, code documentation only works within a wiki, because you are describing special "problems" (the functions are already able to be looked up) - here a wiki is ok.

[Alcon]

Please be a bit patient, your request is being discussed/considered.

Sorry for my impatience. Not used to the speed things move at around here.

To get no false impression... this is not discussed by the developers. What you talk about is modifying code and not documenting it.

Well, you could call putting in comments modifying the code, because it does require that you alter the files the code is in, but it doesn't change the code itself. It's also widely considered to be good coding practice to document, or even over document your code. Especially in open source projects where you expect to have a lot of mod authors working with it.

And he clearly asked for people who would be interested in it or would help him.

Well... yes. The reason I came asking about documentation is because I've been trying to learn the phpBB3 code in order to make modifications to it for my employer. However, my job of learning it has been made rather more difficult than it should be by the lack of documentation. I've had to comb through the code to find places where functions are called and where they are declared to try and figure out exactly what they're doing, how to use them, what each of the parameters are, and what values they can or should contain. A simple block comment above each function declaration stating all of those things would take care of that. And it'd be much easier for the writer of the functions in question to do that than for someone like me who's trying to learn the code. That said, I think it's important enough for open source projects to be well documented -- and I like phpBB enough -- that I'd be willing to attempt the task myself, if there are no other takers.

If I understood his request (and I think I have), he’s asking who would be interested in expanding and building a more thorough documentation of classes, functions and every bit of code in phpBB3 so that it may be more easily understood by MOD Authors and coders who have to work with the phpBB3 Framework.

Head of nail, meet hammer.

One thing I forgot to mention, the Olympus Wiki: http://olympuswiki.naderman.de was built for the purpose of expanding on the code documentation.
I think you’ll find quite a bit of documentation you may be after there, and it would be a great avenue to contribute documentation to as you go through the code.

I did stumble across that and had been using it some, but even that's pretty incomplete. I'll give it another look though, maybe I was just in the wrong section of it. It's definitely a good place to start working. Personally I think the documentation really should be in the form of comments in the code, but a wiki certainly doesn't hurt

The user documentation will never be within a wiki (this is not wanted and will also not work - comments yes, but not wiki). To the contrary, code documentation only works within a wiki, because you are describing special "problems" (the functions are already able to be looked up) - here a wiki is ok.

I don't think I agree with you there. I think a wiki could work perfectly well as a code documentation tool. You'd just have to make sure it was well organized so that it was easy to simply browse to the piece of documentation you wanted. But yeah, I'm with you, comments in the code are a far better method of documentation.

[Highway of Life]

The user documentation will never be within a wiki (this is not wanted and will also not work - comments yes, but not wiki). To the contrary, code documentation only works within a wiki, because you are describing special "problems" (the functions are already able to be looked up) - here a wiki is ok.

I don't think I agree with you there. I think a wiki could work perfectly well as a code documentation tool. You'd just have to make sure it was well organized so that it was easy to simply browse to the piece of documentation you wanted. But yeah, I'm with you, comments in the code are a far better method of documentation.

That’s not what Meik was saying.
User documentation, how to do x from the ACP, MCP, UCP, how to move topics, lock topics, etc... would not really work within a wiki. Whereas Coding Documentation would only work within a wiki (such as naderman’s olympus wiki).

Also judging by your reply, it seems you have not yet read the sourcecode documentation ?

[Alcon]

That’s not what Meik was saying.
User documentation, how to do x from the ACP, MCP, UCP, how to move topics, lock topics, etc... would not really work within a wiki. Whereas Coding Documentation would only work within a wiki (such as naderman’s olympus wiki).

Ahh, my bad, I misunderstood. Then we agree

Also judging by your reply, it seems you have not yet read the sourcecode documentation ?

I have. It's full of holes. It's auto generated from the comments with in the code, right? A lot of those were basically left empty. Though it's gotten a little bit better since last time I looked.