Documentation Roadblocks - Suggestion

Guys, I don't know if this an out of scope request, but I get about 50% of where I want to go with Phalcon and then get hit with a Roadblock regarding documentation to achieve certain goals.

I noticed there is a PHP EXAMPLE SITE but the best part of the PHP site is the Comments section on the individual classes,methods, and functions.

This community would benefit (greatly, immensely, superbly) if the Method calls had their own page like PHP with user comments on the bottom. The best examples of use are sometimes found in that section. (thumb up and down etc)

Please do not put it on Stackoverflow only, there is a dissociation of the Method docs and the people discussing.

It simply does not make sense to try and search these forums repeatedly and hopeful "google something correctly" to find out of site discussion,

I don't need a large community, I need a well organized one !

Rock On!



4.2k
edited Aug '14

Very good idea, I find many answer in the forum. But it takes me a lot of time.



4.9k

I totally agree. Method call with a detailed explanation of each argument will help a lot and with user comments would be great. Currently it is a struggle.



82.3k

I think that is not necessary, if you want to contribute something that improves or clarifies the use of some method/class, it should be added directly to the documentation or to the Phalcon's docblocks in the code which are the source of the API.

Moderate off-topic, inflammatory comments, potential questions, developers submitting bugs right there in the comments and probably many other comments that will be outdated as they are specific to past versions of Phalcon.

Leaving the repositories here, if someone want to improve the documentation:

edited Aug '14

Expecting everyone to push updates to Github is just a roadblock. PHP website has been running for over 15 years with very useful information contirbuted by the users within the comment area.

An item so trivial as this, http://forum.phalconphp.com/discussion/3208/partial-uri-routing

could have been put as a comment and stored forever within this page's elements (this page has 100 things going on and can be daunting) http://docs.phalconphp.com/en/latest/reference/routing.html

It would forever be refernced and perhaps much clearer for those entering the framework. Anyway, random loop I wrote so I don't have to add a new route everytime I create a new feature on my site.

But this will be lost in the forum for no one to read but a couple of people.

$uri_info = parse_url($_SERVER['REQUEST_URI']);
$trimmed_url = ltrim($uri_info['path'], $di->get("url")->getBaseUri());
$trimmed_url = rtrim($trimmed_url, "/");
if(trim($trimmed_url) <> ""){
$url_parts = explode("/",$trimmed_url);
if(count($url_parts) == 1)
{
    if (class_exists(ucwords(strtolower($url_parts[0]))."Controller")) {
        $router->add("/".strtolower($url_parts[0])."/",array("controller" => strtolower($url_parts[0]),"action"     => "index"));
        $router->add("/".strtolower($url_parts[0]),array("controller" => strtolower($url_parts[0]),"action"     => "index"));
    }
} else {
    if(method_exists(ucwords(strtolower($url_parts[0]))."Controller", ucwords(strtolower($url_parts[1]))."Action")){
        $router->add("/".strtolower($url_parts[0])."/",array("controller" => strtolower($url_parts[0]),"action"     => strtolower($url_parts[1])));
        $router->add("/".strtolower($url_parts[0]),array("controller" => strtolower($url_parts[0]),"action"     => strtolower($url_parts[1])));
        if(count($url_parts) > 2){
            $param_string = "";
            for ($i = 1; $i <= count($url_parts); $i++) {
                $param_string .= "/{param".$i.":[a-zA-Z0-9_-]+}.*";
                $router->add("/".strtolower($url_parts[0])."/([a-zA-Z0-9_-]+)".$param_string,array("controller" => strtolower($url_parts[0]),"action"     => 1));
            }
        }

    } else {
        if (class_exists(ucwords(strtolower($url_parts[0]))."Controller")) {
            $param_string = "";
            for ($i = 1; $i <= count($url_parts); $i++) {
                $param_string .= "/{param".$i.":[a-zA-Z0-9_-]+}.*";
                $router->add("/".strtolower($url_parts[0]).$param_string,array("controller" => strtolower($url_parts[0]),"index"     => "here"));

            }
        }
    }
}
}


82.3k
edited Aug '14

Expecting everyone to push updates to Github is just a roadblock. PHP website has been running for over 15 years with very useful information contirbuted by the users within the comment area.

You can contribute any useful information as a pull request instead of a comment. There's no difference, the intention is the same. What's the difference between a comment and a contribution? A contribution would be consise and more elaborated. If you want to add an external link (for instance to a thread in the forum) you can follow the same structure that it currently has:

http://docs.phalconphp.com/en/latest/reference/applications.html#external-resources