Document installation process

[augustohp]

It is imperative that we have ways to enable documentation on how to install the given component. We have some use cases within Respect itself that should cover the 80-20 rule:

• Read package.xml for basic information on a pear-basis installation
• Support composer.json for Composer support

[alganet]

+1

[augustohp]

Yesterday me and @henriquemoody discussed that issued and came to a discussion on where this feature fits best:

• Doc
• Foundation

My vote is for Doc.

[alganet]

Doc +1

[henriquemoody]

How can Doc read the package.xml if it doesn't know when are the package.xml? My vote is for Foundation, but make possible to pass the package.xml for Doc or something like this.

[alganet]

Integrations such as this one are hard. It has the same problem as the git blame integration to find authors for classes and functions.

Respect\Doc was about documenting classes, then evolved to document namespaces. Now its time to evolve to documenting projects, so It should be aware of package.xml, .travis.yml, composer.json, Makefile, .git folder and others.

Maybe we should add this as metainformation. Current API is:

$doc = new Respect\Doc('My\Namespace');

Proposed new API is:

$doc = new Respect\Doc('My\Namespace', '/my/project/folder');

Second parameter is optional, it adds metadata seamlessly to the generated docs. Since our current ideas are mostly tied to files and folders inside the root folder of a project, this could do.

[henriquemoody]

1+

[augustohp]

And that makes Doc API compatible with CLI and other things =D

[iannsp]

what about do an annotation into target class, like: if we will document as it... $doc = new Respect\Doc('My\Namespace');

the class inside this namespace have annotations about data we use into heuristic algorithms to find details about the project and document it. some notes like if it is psr-* compliance, what descriptor are used liek package.xml or composer.json and so on.

[augustohp]

I would like to avoid annotations if possible. Using annotations to solve this kind of problem will lead us into a scenario where Doc will only work on prepared code bases, just like PHPDoc, and i think this is very much the main difference from it. I think it is cool to try and force ourselves on making Doc compatible with any PHP codebase.

We can use Foundation to provide us a lot of information from packages (like Composer and Pear). In relation to the heuristic algorithms I don't have much to say T.T

Now, regarding the proposed new interface:

$doc = new Respect\Doc('My\Namespace', '/my/project/root/folder');

+1 for that interface, but we will still missing how are we going to extract all the data we need from the project. Just for clarification, I am moving specifically the discussion on how we are going to do that in another issue.