Respect / Doc

Generates docs that rocks your socks off.
BSD 3-Clause "New" or "Revised" License
14 stars 0 forks source link

Bind issues to documentation #13

Open augustohp opened 12 years ago

augustohp commented 12 years ago

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 commented 12 years ago

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 commented 12 years ago

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

iannsp commented 12 years ago

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 commented 12 years ago

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 commented 12 years ago

+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 commented 12 years ago

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 commented 12 years ago

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 commented 12 years ago

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

augustohp commented 12 years ago

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 commented 12 years ago

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

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

augustohp commented 12 years ago

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

iannsp commented 12 years ago

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 commented 12 years ago

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 commented 12 years ago

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 commented 12 years ago

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 commented 12 years ago

its like a note = [note]

;)

nickl- commented 12 years ago

@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?