Bind issues to documentation

[augustohp]

This is an idea me and @alganet talked just a little today.

It would be useful to have some king of pattern to write issue titles, so we can bind them to the documentation and tests somehow. This allied with fossil-scm would be awesome++!

[iannsp]

If u guys talk about issues from Here(github)
I can port githubit to php to have no external dependency and why can use it to bind the contents in someway

[alganet]

That would be awesome! We need to talk more about this, seems promising.

[iannsp]

what you guys think about this idea here?
if you like to bind some github issue into resultant documentation you can note something like
/**
*@github issue 13
*/
its a open, extensible notation because promote other uses like
note.: its just a proposition exercise
@googlecode issue 13
@github gist iannsp/2
and so on....
you guys like this?
reflection and a little of gummiberry juice can implement it.

[augustohp]

We have some ways to do it. PHPUnit already has a @ticket annotation we can make use of. That would make us more compatible with pre-existing code.

But how we are going to know the full URL of that ticket?
Foundation provider architecture should be quite useful for that of thing also, what concerns me the most is using Foundation+Doc in Doc. Although it seem quite a nice combination for me, it bother me that Doc needs another Respect component to run; on the other side, replicating a lot of providers from Foundation into Doc is worse.

PS: already mentioned the need of project information provided by Foundation in issue #4

[alganet]

+1 for @ticket. Projects don't use more than one bug tracker, so a single annotation (and even better: a existing one!) is sufficient.

[iannsp]

yes, a Project does not use more then one bug track but docs need handle with whatever bug track the team use for it.
then we need to handle the @ ticket (and I agree with the use of it) as a information form different sources, not for a single project but for any project become use the Respect Doc.

[augustohp]

As seen on #17 this could be done like this:

<?php
$doc = new Respect\Doc();
$doc->fromSources('src/*.php')
    ->fromTests('/test/*Test.php')
    ->fromPackages('composer.json', 'phpunit.xml')
    ->withIssuesOn('http://github.com/Respect/Doc/issues/%s')
    ->generate();

Just a sprintf on that string we can put the @ticket data at the placeholder for it and just be happy. If no placeholder for the string is given, just appending it to the end of the string should do trick also.

@iannsp Couldn't agree more with you on making Doc "usable" by any project #happypanda

[alganet]

And why not $doc->fromSources($a)->fromTests($b)->withGithub('Respect/Doc')->find('Respect\Loader')->methods?

[augustohp]

Why not!? I like the idea of a withGitHub(), but I would love the idea of it being just a decorator to the withIssuesOn method. This way we still compatible with practically any ticket system =P

PS: don't know about the decorator, we certainly don't need that pattern there.

[alganet]

Decorator +1. (more like a fluent composite builder meta-programmed =P)

Also, did you noticed the find() and ->methods? 8-)

[augustohp]

Of course I noted, hard to pass this API things through my eyes without smiling these days =P

[iannsp]

guys.
I'm proud off you. ;)
this represent an amazing solution to the problem...
off course its a good way of add more good stuffs to Doc and in the happy panda way.
+1 for decorator and probably believe this one is good too.

<?php
$doc = new Respect\Doc();
$doc->fromSources('src/*.php')
    ->fromTests('/test/*Test.php')
    ->fromPackages('composer.json', 'phpunit.xml')
    ->versionIn(new Github('respect/doc')) // or new SVN('/home/iann/Project/Respect/Doc')
    ->generate();

[iannsp]

I almost forgot to note the fact if I use new GitHub(...) I can Handle with all dependencies like find for issues, commiters and others.
The same is true for other like svn, mercurial ....
It isolate the main implementation Respect/Doc itself from the version control implementations and permit reuse this into others parts of Respect.

[augustohp]

Just a note: @alganet likes to use builders in that fluent way, this means every magic method is a builder for a given class. If we carefully name the classes, we can reach then by the magic method call name.

All projects on Respect follows these rules on fluent interfaces, so you don't have to use it that way (fluently) and better: you don't have to test it that way (it would suck hard!). Try and have a look at Rest ou Validation for instance. Relational is another good candidate also =P

[augustohp]

Just another note: I hate builders. And I know that "Hatters gonna die", but using builder+fluent interface really makes sense and is a beautiful usage of the pattern.

[iannsp]

its like a
note = [note]

;)

[nickl-]

@iannsp Yes as @augustohp is mentioning @alganet's example has tricks up its sleeves =)

<?PHP

$doc->fromSources($a)->fromTests($b)->withGithub('Respect/Doc');

Would usually mean an interface there somewhere and the __call($name, $params) would be making a
new WithGitHub('Respect/Doc') instance so you are on the right track

I have just testet it and the following work hehehehe =)

<?PHP

$doc->fromSources($a)->fromTests($b)->withBitBucket('Respect/Doc');

$doc->fromSources($a)->fromTests($b)->withSourceForge('project/RespectDoc');

$doc->fromSources($a)->fromTests($b)->withTwitter('#phprespect');

Someone must just do the find, panda's anywhere?