Branch or Patches for PHPDoc Blocks

[Amy Stephen]

I would like to help get the PHPDoc Blocks work rolling and need direction. Last June, Marius van Rijnsoever created a patch to show the type of work that needs to be completed before we can begin using the automated documentation tools for documenting the API. He also left the following question at the bottom of the page as to how best to proceed, be it single patches or a branch. Unfortunately, since the example patch was committed and marked "Fixed in SVN", the question went unnoticed.

Submitted By: marius van rijnsoever
Adddate: 2010-06-02 01:30:53
Thanks for all your feedback!

The question then becomes, do you want me to apply the coding standard and
correct docblocks for all the files in the library directory? And how will the
logistics of that work (if the .patch files need to be applied manually for all
files this will generate an enormous workload)

What is the best way? If we need a branch, would one please be created for this purpose?

Thanks!

[Mark Dexter]

I think you could use either approach. If you do a patch, maybe you could do them in groups to keep the patch sizes down. If you want a branch, let me know and I'll set one up. Thanks. Mark

--
You received this message because you are subscribed to the Google Groups "Joomla! CMS Development" group.
To post to this group, send an email to joomla-...@googlegroups.com.
To unsubscribe from this group, send email to joomla-dev-cm...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/joomla-dev-cms?hl=en-GB.

[Janich]

Correct documentation is very good to have for the developers.
I've been longing for it from before 1.6 ga, but yet havent had the
time to look into all errors (the errorlist from phpdoc is quite long
iirc).

Anyway - I believe I can help with correcting errors and wrong
conventions too.
Branch or patches? It doesnt matter to me personally, but being
multiple people on this subject requires some coordination I
believe...

My time is currently very limited at this moment, so I'll probably
have a lot easier being told where to put my efforts... But I'll
follow this thread anyway now.

@Amy - Please do send me a mail if you want help on this or need any
inputs from me.. :)

On Mar 2, 5:32 am, Mark Dexter <dextercow...@gmail.com> wrote:
> I think you could use either approach. If you do a patch, maybe you could do
> them in groups to keep the patch sizes down. If you want a branch, let me
> know and I'll set one up. Thanks. Mark
>

> On Sat, Feb 26, 2011 at 4:54 AM, Amy Stephen <amystep...@gmail.com> wrote:
> > I would like to help get the PHPDoc Blocks work rolling and need direction.

> > Last June, Marius van Rijnsoever created a patch<http://joomlacode.org/gf/project/joomla/tracker/?action=TrackerItemEd...>to show the type of work that needs to be completed before we can begin

> > using the automated documentation tools for documenting the API. He also
> > left the following question at the bottom of the page as to how best to
> > proceed, be it single patches or a branch. Unfortunately, since the example
> > patch was committed and marked "Fixed in SVN", the question went unnoticed.
>

> > Submitted By: marius van rijnsoever <http://joomlacode.org/gf/user/mariusvr/>

[Andrew Eddie]

I've got some time to devote to this effort so am happy to help. I'm
also working on a sniff file for a client and they are happy to share.
Happy to help lead or be lead - whatever suits everyone.

There are a couple of easy places to start:

1) Add missing class/method/function docblocks - there are a lot.
2) Ensure there is a reasonable description in all
class/method/function docblocks.
3) Ensure that @params tags have the variable name in place, eg:

@param integer $foo A variable

4) Ensure @return is provided for all functions and methods, even if
it's @return void
5) Ensure @since is provided and accurate for all classes, functions
and methods.

In terms of files, the best place to start is picking a file or
package in the framework. Then move to the /includes/ folders of the
site and administrator applications, then move into the CMS more
generally.

Personally I think patches are a better way to go, placed under the
"Code Style" category in the 1.6 issue tracker. I don't see any
reason why code style can be improved during maintenance phases.
Also, while 1.6 should be the priority, it wouldn't hurt to give 1.5
some love in this area.

Most doc generators give some sort of error reporting. I'm leaning
towards Doxygen nowadays - happy to share my setup file with anyone
that wants it. In terms of keeping track of who is doing what, I'd
say a Google spreadsheet would be simple enough to set up to manage
that.

My 2c.

Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla 1.6 developers

[Andrew Eddie]

Ok, just some clarification on "patches" and/or "branches".

If you are cleaning up any of the CMS (components, modules, etc), use
patches and the issue tracker and/or branches in the Joomla SVN repo.

If you are doing anything in the platform (aka framework:
/libraries/joomla), then please fork off (no, I'm not swearing at you)
https://bitbucket.org/joomla/joomla-platform using Mecurial. This will
be a good test bed for the new system. If a few people want to get
behind creating Mecurial docs that would be great to.

Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla 1.6 developers

[Dave Havard]

I would be up for helping with this. Just spent yesterday grappling with the JNestedTable class and docs would really have helped (make sure your lft and rgt columns are signed would have been a god send! :-s...)

[Amy Stephen]

Boy, this is good to see. Thanks Mark, Janrich, Andrew, and Vividearth.

Andrew - I was wondering about the framework effort, thanks for that.

Marius and I have been just missing one another this past week as we have tried to talk on this. I know he's done some work/thinking on this already so we'll want his ideas on good ways to proceed, too. I'll point him to this discussion and see what his thinking is.

I agree with Andrew that if we can section off the code base by packages/files that would be a good organizational approach. We could create a Google Doc list and have devs sign up for a section and maybe get this spread out a bit and accomplished more quickly. The better able we are in describing exactly what needs to be done, the easier it will be to involve people.

If anyone else is willing to help, post in, and let's see what ideas Marius has, in addition to those already mentioned, and get this taken care of so the API is available for devs to do cool stuff.

Thanks so much everyone!

[Andrew Eddie]

Ok, just some follow up after playing last night. I think this is
going to be easier to track than I thought.

I've put my sniff for PHP CodeSniffer in a new repo here:
https://bitbucket.org/eddieajau/joomla-api-support

It's not perfect yet but it's a good start.

Slowly tuning it as I go through the framework. There's also my
"trial and error" Doxygen file there for people wanting to play with
that to generate API docs. There are some quirks I've found but maybe
best to start a new thread for that.

I'm committing my work into
https://bitbucket.org/eddieajau/joomla-platform so basically all
people need to do is "follow" that, and if anyone else is working on
anything just let me know and I'll follow your repo (or send me a
"pull request"). Other key people to follow at this time are Louis,
Ian, Sam and Omar (just for your information).

So far I've done (meaning the sniff passes) the /filesystem/ package,
JDatabaseQuery and I'm working on JController, JModel and JModelList.
If I haven't been able to quickly work out what an @param is supposed
to do, I've put in

@param foo $bar TODO Add text

so Eclipse will pick that up and people can backfill as they work
things out more.

I must say I'm really digging Mercurial. It's taking a while to get
out of the very rigid Subversion mindset but I'm enjoying the process
of liberation :)

Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla 1.6 developers

[Andrew Eddie]

Hi Dave

Yeah, that's a bit of a gotcha.

Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla 1.6 developers

[marius]

On Mar 4, 4:11 pm, Dave Havard <david.hav...@gmail.com> wrote:
> I would be up for helping with this. Just spent yesterday grappling with the
> JNestedTable class and docs would really have helped (make sure your lft and
> rgt columns are signed would have been a god send! :-s...)

Here is JTableNested with doygen generated docs :)
http://www.jfusion.org/api16/class_j_table_nested.html

There are at least 3 existing sniffer profiles for Joomla out there
(plus I have custom made sniffer profile on my PC as well. Some links
to existing work:
http://docs.joomla.org/Joomla_CodeSniffer
http://forge.joomla.org/gf/project/jcodesniffer/frs/?action=&br_pkgrlssort_by=package_name&br_pkgrlssort_order=asc
http://www.google.com/url?sa=D&q=http://rouvenwessling.de/joomla/joomla16/

Its probably best to split up sniffer profiles into three categories:
1) docs 2) code style and 3) security. As these will be used by
different workgroups.

Integration with eclipse is very easy:
http://www.phpsrc.org/
http://hakre.wordpress.com/2010/03/06/php-code-sniffer-eclipse-and-wordpress/

Doxygen would be better to use than phpdocumenter (that project has
been abandoned long time ago) and therefore not really necessary to
adhere to all phpdocumentor requirements (doxygen has much more
flexible tag system). Also need to keep in mind that docblock tags
need be optimised for IDE useage such as eclipse (need to use the
actual object class name instead of just "object").

Exciting to see some movement on this topic :)

If patches are the "poison of choice" that's fine with me :) Is the
code style tracker already active or does this need to be created
still?

Kind regards, Marius

[Mark Dexter]

I really like the link with the doxygen documentation. Are we planning on using that for our "official" api? Mark

[Andrew Eddie]

Hi Marius

I saw Arlen had the start of a sniff, but all it was doing was setting
the ordering for the docblock tags. I also couldn't find if you'd
published your anywhere. All I've done with my sniff is take the PEAR
standard (plus a dash of Squiz) and whittle away at it. There's a few
things it doesn't do, like check tab indenting, but it's a reasonable
start for the code standard side of things.

Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla 1.6 developers

[Paladin]

Now that brings back memories of long hours writing/reading messages on the framework list, as well as over skype on the task of coding standards.

The first codesniffer I wrote, back in the day, did quite a bit; went nearly all the way towards implementing the coding standard that you and Louis could agree on (which in turn wasn't the published standard at the time, for that matter). But it appeared no one was interested in using, so it languished unused and unloved on github for quite a while.

In the interim the codesniffer project changed their approach to sniffing, and my original code wouldn't work with the new version of phpcs, so I picked it up to build it again, this time with some feedback from Louis requesting a different standard than the one we'd talked about years ago. And that's what's there now. (I think the jf project version is the same as the github one, I just placed it there as well to see if I could get anybody interested in it; github is the authoritative repo for my OS projects, but I'll post copies elsewhere and try to keep everybody sync'ed if there's a reason to. I'll check it after posting this comment, and if they're different, I'll update the jf one.) From what I remember, the wiki also could use some serious pruning/editing on this subject, as it used to contain multiple pages on the subject with conflicting information. (I added a wiki page back in the day about the codesniffer, but I'd have to go back and review it to see if it's still accurate.)

And it does more than simply check docblocks. For example, run against the copy of loader.php I currently have it flags several incorrect if blocks, badly named private member variables, badly formatted switch/case blocks, etc. Total of 33 flags (11 are not in docblocks) affecting 25 lines. It also takes a stab at tab indents, given 4 chars per tab stop.

I'm glad to see some interest finally in cleaning up the codebase. I don't have as much time as I did back when I first offered to clean it up on my own, but I'm still interested in helping people get started on the idea, if they're willing.

[Paladin]

And I see a couple of bugs got filed. Thanks, Kevin. Good to see someone paying attention, even after I got disappointed. I'll get right on them.

[Andrew Eddie]

Arlen, please don't confuse "people don't have time to look at this
right now" with "nobody is interested". Speaking for myself, I've
*always* been *interested* in this subject but not always had the time
to be involved in everything that everyone would like me to, but if
people want to stop what they are working on for whatever reason, who
am I to judge. I for one will be very happy for anyone that has time
to help get this all sorted.

Regarding sniffs, my apologies, it (joomlacode repo) does have a sniff
for the switch declaration but I can't find any other. The current
version of phpcs seems to do in all in ControlSignatureSniff.php now -
you just put all the formats in an array.

Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla 1.6 developers

[Paladin]

Andrew, I used the phrasing "it appeared..." deliberately to avoid claiming that it was anything other than an appearance. I try to avoid comment on what goes on in other people's heads, although I concede the choice of the word 'finally' there at the end could have been interpreted variously (I'd intended "finally" as a modifier to my seeing the interest not as a modifier to the existence of the interest, as in "finally I see" rather than "finally there is") and thus ill-advised and not in keeping with the way I began the post. 

You don't se any other control structure sniffs because in the last communications Louis and I had over this, he said to use PEAR standards for them all, and in ruleset.xml I tell it to use PEAR (which installs with phpcs) unless specifically directed not to. The only reason for not using PEAR for switch/case was the double indent (SWITCH indent CASE indent CODE). PEAR standard is a single indent for the switch/case block. Just because I didn't write the code to check it doesn't mean it's not getting checked.

Just like it was using the PEAR class name convention until Kevin pointed out I'd missed the "mod" and "plg" classes, so I wrote a ValidClassNameSniff.php file to account for that.

[Andrew Eddie]

Ok, I see what you are doing. Where do I find ValidClassNameSniff.php?

Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla 1.6 developers

[Paladin]

It's not in the release bundle yet, because I'm still considering
whether the change I committed for the other bug fix (parsing the
copyright statement for the existence of something that could be
called a name) is the right way to go. I committed the copyright
change and mistakenly called it fixed in tree, but left it as open
status in the tracker. And even so there's still a bug in the code.
It's a silly bug and simple enough to fix (I changed some parens in
the regex, and didn't change the code that referenced them) but before
I went any farther with it I wanted to be sure that was the right was
to go. The ValidClassNameSniff.php file is in the svn tree, it's
either rev 7 or rev 8, not sure at the moment which but I think it's
8.

The problem I'm thinking about is this:

1) Copyright 2005 - 2011 Open Source Matters
2) Copyright 2005 Open Source Matters
3) Copyright 2005 2011 Open Source Matters

Statements 1 and 2 above are valid, 3 is not. But the original code
only passed statement 1 and called both 2 and 3 invalid. The current
code now in the svn tree calls all three valid. I'm nearing a limit of
regex with this because the only regex I can think of offhand which
would call 1 & 2 valid while calling 3 invalid would also call these
statements invalid:

4) Copyright 2005 1234Berea Street Web Development
5) Copyright 2011 2016 Olympics Committee

While these would not likely be found in core code, the intent is to
be usable for more than just core, and I don't want to call a name
invalid simply because it begins with 4 numbers. The coding standard
currently does not call for a specific delimiter (such as the word
"by", which would be a simple solution) between the date and the name,
rendering the ability to tell the meaningful difference between the
typo that creates statement 3 and the valid formulation which is
statement 5 problematic without building a grammar parser.

As of now, one of the options I'm toying with is adding an additional
option to toggle between a more strict core code statement (which
would check for Open Source Matters, not just any name) and a looser
parsing that would allow statements 3, 4 & 5 to pass. But I'm going to
let that percolate through my subconscious for the next couple of
days, maybe it'll come up with something new.

On Mar 7, 5:57 pm, Andrew Eddie <mambob...@gmail.com> wrote:
> Ok, I see what you are doing.  Where do I find ValidClassNameSniff.php?
>
> Regards,

> Andrew Eddiehttp://learn.theartofjoomla.com- training videos for Joomla 1.6 developers

[Amy Stephen]

I am also interested in helping but I don't know how. I'm going to need some instructions if someone can kindly explain how to get started.

Thanks!

[Andrew Eddie]

Thanks.

I'll sync up with what you've done later this week.

Regards,
Andrew Eddie
http://learn.theartofjoomla.com - training videos for Joomla 1.6 developers

[Paladin]

If you're developing on Windows, I won't be much help, I'm afraid
(Windows just makes PHP development too much work). But here's a
couple of resources to get started with the Code Sniffer:

http://pear.php.net/package/PHP_CodeSniffer/download/
http://docs.joomla.org/Joomla_CodeSniffer

The two known bugs in the release bundle aren't that serious.
Workaround for single copyright year is to end the year with " -" (or
you can just accept the wrong diagnosis, knowing it will be fixed
soon) and you can just accept the class name flags for "modXxxx" and
"plgXxxx" class names.

Getting PEAR installed on a Windows machine is where I'll fall short.
Once PEAR is installed and working, the install instructions for both
the sniffer and the specific Joomla Standard should work fine. I keep
telling myself I should go through installing PHP and the rest on my
Win7 test machine, but then I ask myself why, since I do my work on
Linux and OS/X, and post to Linux servers? So I don't. Selfish, I
know, but there it is.

And if you've used git, Hg won't be much of a change. Just take git
and remove about half the functionality. So far the biggest difference
I've found (aside from things being left out, of course) is Hg
switches the effects of "fetch" and "pull." Think "Git Lite" and
you'll be right on track.

[Paladin]

Let me know if you want the tests I wrote as well. I didn't think the
average user of the sniffer would be interested in them, so while
they're in my local tree, they're not in the release bundles.

On Mar 8, 12:25 am, Andrew Eddie <mambob...@gmail.com> wrote:
> Thanks.
>
> I'll sync up with what you've done later this week.
>
> Regards,

> Andrew Eddiehttp://learn.theartofjoomla.com- training videos for Joomla 1.6 developers
>

> >> Andrew Eddiehttp://learn.theartofjoomla.com-training videos for Joomla 1.6 developers