İstek params ve phpdoc [yinelenen]

2 Cevap php

Possible Duplicate:
Is there a standard for documenting GET/POST parameters?

Mantıklı bir şekilde phpdoc yoluyla istek parametrelerini belgelemek için en iyi şekilde anlamaya çalışıyorum. Özellikle, ben GET / POST aracılığıyla parametreleri almak bazı Zend Framework denetleyici eylemleri var, ama işlevsel params değildir ettik. Bu mantıklı mı?

/**
 * Display a pagination/grid list of rows.
 *
 * @param string $_GET['order']  What field to sort on
 * @param string $_GET['dir']    Direction to sort; either ASC|DESC
 * 
 * @return void
 */
public function listAction()
{
    $order = $this->_request->order;
    ...

Ben bu yöntem için dokümanlar oluşturulur ise, "düzen" ve "dir" Bu yönteme bir url dizesi yoluyla geçirilebilir bir gösterge olmaz. Sadece yapmak daha mantıklı olur

@param string $order

Ben var yerine @ kullanmalı mıyım?

Düşünceler hoş geldiniz.

2 Cevap

Ben @ param oynayana önleyeceğini.

Ayrıca kodu bariz yapmak için bir _validate () yöntemi yapabiliriz. Sonra birim test için bir seam oluşturmak için () _validate kullanabilirsiniz.

/**
 * Display a pagination/grid list of rows.
 *
 * Requires $_REQUEST['order'] and $_REQUEST['dir']
 * 
 * @return void
 */
public function listAction()
{
    list($order, $dir) = $this->_validate($this->_request);
    ...

private function _validate($request) {
    if (!$request->order)
         throw new InvalidArgumentException('"Order" must be in request');

    if (!$request->dir)
         throw new InvalidArgumentException('"Dir" must be in request');

    // maybe clean vars???
    //Zend_Filter_Numeric.....

    return array($request->order, $request->dir);
}

Ben genellikle teklif ne kullanmak veya kod çok uzun zaman olmayan basit phpdoc yorum koymak, ya da sadece bir şey yapmak ya.

Bu üç parti arasında, çözüm iyi, ben inanıyorum.


Only one thing that you should check : does this render nicely when you are generating the phpdoc ?

Phpdoc Eğer doc-blok vermek adlarını kullanır gibi teoride, ben gerektiği herhalde ...

Evet ... eh, ben daha iyi bir yol görmüyorum; daha iyi bir yol değil ihtiyaç: Bunu daha anlaşılabilir / okunabilir / daha temiz bir şey yapabileceğini sanmıyorum.


I do not like the 

@param string $order

fikir: hiçbir şey $order $_GET verilen ve bir "gerçek bir yöntem parametresi" değildir olmalıdır gösterir; ben daha ziyade bu sözdizimi önlemek istiyorum.


I never user @var for parameters, btw : only for variables, when I feel the need of documenting them (which is not often ; at least for short methods / parts of code)

etiketler