Post Reply 
 
Thread Rating:
  • 0 Votes - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
phpDocumentor?
08-25-2018, 04:29 AM (This post was last modified: 08-25-2018 04:39 AM by bigpower10.)
Post: #1
phpDocumentor?
I'm interested in contributing to this project. As I am new, I need to get up to speed on the code base before I start hacking away.

I was thinking that a good first learning project to undertake might be to add in-code documentation, a la phpDocumentor. In addition to giving me a chance to thoroughly walk through the code the documentation could help other newbies get up to speed given the mix of architectures going on (lots of procedural code, some OOP, some 3rd party modules..). I've used phpDocumentor on projects in the past and it's pretty awesome.

Would there be any objections to adopting the phpDocumentor standard within the code? i.e., no functional code changes, just phpDoc doc blocks (glorified comments) and maybe standardization of white-spaces between code blocks?

- Bryce
Find all posts by this user
Quote this message in a reply
08-25-2018, 05:13 AM
Post: #2
RE: phpDocumentor?
Sounds good to me. But I don't have the final say so it depends what others say.
Visit this user's website Find all posts by this user
Quote this message in a reply
08-26-2018, 01:12 PM (This post was last modified: 08-26-2018 01:15 PM by phil.)
Post: #3
RE: phpDocumentor?
We've actually really tried hard through long variable names, consistent syntax - minimising abstraction wherever possible and a whole lot of other conventions - sometimes even at the expense of code reuse - to make the code as readable as possible.

http://www.weberp.org/CodingConventions.html

My experience with documentation produced by such systems is not great to be honest. However, that is a long time ago. Also, given that the code is pretty readable - we wouldn't wish to direct people to some other documentation about the code - when the code itself is actually the best manual and authoritative? I may not be understanding things properly?
I wonder if a venture into developing additional practical functionality like the time-sheet idea would not be a more worthy goal?
Sorry about the cold water ...

Phil Daintree
webERP Admin
Logic Works Ltd
http://www.logicworks.co.nz
Visit this user's website Find all posts by this user
Quote this message in a reply
08-27-2018, 10:41 AM
Post: #4
RE: phpDocumentor?
Understood, no worries. If it's all the same, I'm going to proceed with the documentation, even if it never leaves my personal fork. The act of going through each file, line by line, and following the execution path has already proven super valuable to me.

I'm treating this as an intermediary step on the way to doing the other fun stuff. If anyone wants to take a look at some of the commented files, check these out:

- Bryce
Find all posts by this user
Quote this message in a reply
08-27-2018, 11:01 AM (This post was last modified: 08-27-2018 11:41 AM by phil.)
Post: #5
RE: phpDocumentor?
Looks like you are being thorough and as you say no real substitute for going through the code to get to grips with what is going on - especially the key scripts used in virtually all scripts like the first 2 listed and:

includes/GetConfig.php
includes/header.php
includes/LanguageSetup.php
includes/ConnectDB.inc and DB abstraction to ConnectDB_mysqli.inc

Phil Daintree
webERP Admin
Logic Works Ltd
http://www.logicworks.co.nz
Visit this user's website Find all posts by this user
Quote this message in a reply
08-27-2018, 04:36 PM
Post: #6
RE: phpDocumentor?
I don't think that properly commenting the code breaks any coding guidelines. It looks to me that what Bryce has done enhances the readability of the code without breaking any of the fundamental principles behind weberp. Seems a bit of a no brainer to me.

Tim
Visit this user's website Find all posts by this user
Quote this message in a reply
Post Reply 


Forum Jump:


User(s) browsing this thread: 1 Guest(s)