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.
Better Documentation for the Code
Forum rules
Discussion of general topics related to the new release and its place in the world. Don't discuss new features, report bugs, ask for support, et cetera. Don't use this to spam for other boards or attack those boards!
Discussion of general topics related to the new release and its place in the world. Don't discuss new features, report bugs, ask for support, et cetera. Don't use this to spam for other boards or attack those boards!
-
- Registered User
- Posts: 4
- Joined: Wed Jul 02, 2008 1:53 pm
- Location: Saratoga Springs, NY
- Contact:
Better Documentation for the Code
The road goes ever on and on, down from the door where it began.
Now far ahead the road has gone, and I must follow if I can.
-Bilbo Baggins
The Road Goes On
Now far ahead the road has gone, and I must follow if I can.
-Bilbo Baggins
The Road Goes On
-
- Registered User
- Posts: 4
- Joined: Wed Jul 02, 2008 1:53 pm
- Location: Saratoga Springs, NY
- Contact:
Re: Better Documentation for the Code
Would people be interested in a project like this? Or perhaps I should ask, would people like to see this done?
The road goes ever on and on, down from the door where it began.
Now far ahead the road has gone, and I must follow if I can.
-Bilbo Baggins
The Road Goes On
Now far ahead the road has gone, and I must follow if I can.
-Bilbo Baggins
The Road Goes On
- Highway of Life
- Registered User
- Posts: 1399
- Joined: Tue Feb 08, 2005 10:18 pm
- Location: I'd love to change the World, but they won't give me the Source Code
- Contact:
Re: Better Documentation for the Code
Hi Alcon,
Please be a bit patient, your request is being discussed/considered.
Thanks.
Please be a bit patient, your request is being discussed/considered.
Thanks.
Re: Better Documentation for the Code
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.
And he clearly asked for people who would be interested in it or would help him.
- Highway of Life
- Registered User
- Posts: 1399
- Joined: Tue Feb 08, 2005 10:18 pm
- Location: I'd love to change the World, but they won't give me the Source Code
- Contact:
Re: Better Documentation for the Code
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.
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
- Registered User
- Posts: 133
- Joined: Mon Jun 27, 2005 8:46 pm
- Location: Manchester, UK
- Contact:
Re: Better Documentation for the Code
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 
Re: Better Documentation for the Code
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.
-
- Registered User
- Posts: 4
- Joined: Wed Jul 02, 2008 1:53 pm
- Location: Saratoga Springs, NY
- Contact:
Re: Better Documentation for the Code
Sorry for my impatience. Not used to the speed things move at around here.Please be a bit patient, your request is being discussed/considered.
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.To get no false impression... this is not discussed by the developers. What you talk about is modifying code and not documenting it.
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.And he clearly asked for people who would be interested in it or would help him.
Head of nail, meet hammer.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.
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 hurtOne 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 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.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.
The road goes ever on and on, down from the door where it began.
Now far ahead the road has gone, and I must follow if I can.
-Bilbo Baggins
The Road Goes On
Now far ahead the road has gone, and I must follow if I can.
-Bilbo Baggins
The Road Goes On
- Highway of Life
- Registered User
- Posts: 1399
- Joined: Tue Feb 08, 2005 10:18 pm
- Location: I'd love to change the World, but they won't give me the Source Code
- Contact:
Re: Better Documentation for the Code
That’s not what Meik was saying.Alcon wrote: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.Acyd Burn wrote: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.
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 ?
-
- Registered User
- Posts: 4
- Joined: Wed Jul 02, 2008 1:53 pm
- Location: Saratoga Springs, NY
- Contact:
Re: Better Documentation for the Code
Ahh, my bad, I misunderstood. Then we agreeThat’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).
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.Also judging by your reply, it seems you have not yet read the sourcecode documentation ?
The road goes ever on and on, down from the door where it began.
Now far ahead the road has gone, and I must follow if I can.
-Bilbo Baggins
The Road Goes On
Now far ahead the road has gone, and I must follow if I can.
-Bilbo Baggins
The Road Goes On