o que falta na api do cake (era- Re: Re: Olá amigos !!)
Marcelo Andrade
> Dá uma olhada na API do Qt e compara com a do Cake.
> A API do Cake é *muito* fraca.
Pra mim ela é razoável. Mas de fato eu nunca desenvolvi com
Qt e já uso Cake há algum tempinho, então meu ponto de vista
pode não ser base de comparação.
Particularmente lembro que tive um impacto quando mudou da
versão anterior para esta nova (esqueci o nome do projeto agora).
Um recurso que usava e muito eram relação de links para
membros de classes. Quando estava começando e não sabia
direito qual era mesmo a classe onde tinha o beforeFilter :), aquilo
me ajudava muito.
Quando mudou a versão da API, solicitei este recurso na lista
gringa e o Gwoo me apontou o link do projeto e que a gente
tinha liberdade de modificar e até gerar a documentação na
nossa própria máquina e tudo. Como na época ainda estava
começando e tinha pouquíssima proficiência com Cake, não
tive como implementar isso que queria :-(
Então, será que não conseguiríamos fazer uma lista do que
falta exatamente na API do Cake??? Posso incluir esse item
que é algo que acho útil e de que ainda sinto falta.
1) relação de links para os membros (nomes de atributos e
métodos) das classes;
2) q+ ???
Alguém continua?
Atenciosamente.
--
MARCELO DE F. ANDRADE
Belem, PA, Amazonia, Brazil
Linux User #221105
"I took the red pill"
Gabriel Gilini
atributos. Não tenho nada contra o formato da API, mas sim com o
conteúdo.
O Nate disse outro dia que eles erraram feio em não ter documentado no
código decentemente desde o começo, e isso atrasou muito o processo de
gerar uma documentação decente pro Cake. Se tudo fosse muito bem
explicado e contivesse exemplos de uso, não haveria problema algum na
minha visão.
2009/12/17 Marcelo Andrade <mfan...@gmail.com>:
> --
>
> Recebeu esta mensagem porque está inscrito no grupo "CakePHP Tuga" dos Grupos do Google.
>
> Para publicar uma mensagem neste grupo, envie um e-mail para cakep...@googlegroups.com.
> Para anular a inscrição neste grupo, envie um e-mail para cakephp-pt+...@googlegroups.com.
> Para ver mais opções, visite este grupo em http://groups.google.com/group/cakephp-pt?hl=pt-PT.
>
>
>
--
Gabriel Gilini
Marcelo Andrade
> Sinceramente o que faz falta é a boa documentação dos métodos e
> atributos. Não tenho nada contra o formato da API, mas sim com o
> conteúdo.
> O Nate disse outro dia que eles erraram feio em não ter documentado no
> código decentemente desde o começo, e isso atrasou muito o processo de
> gerar uma documentação decente pro Cake. Se tudo fosse muito bem
> explicado e contivesse exemplos de uso, não haveria problema algum na
> minha visão.
Mas o que EXATAMENTE? Qual método que tentaste usar
e tiveste dificuldade por conta da API? E como tu achas que
poderia melhorar?
Atts.
--
MARCELO F ANDRADE
Belem, Amazonia, Brazil
Gabriel Gilini
Sei que existem métodos que não tem documentação alguma, e nenhum
atributo é documentado em lugar algum.
2009/12/17 Marcelo Andrade <mfan...@gmail.com>:
Juan Basso
1) Use uma IDE que leia os comentários de Doc, assim você estará
usando a API exata para sua aplicação.
2) Leia o código fonte do cake. Lá você encontra o que precisa e as
vezes mais. Além disso, consegue ver qual a lógica estão utilizando,
para ver se realmente é aquilo que você queria que fosse feito.
Juan Basso
On 17 dez, 18:58, Gabriel Gilini <gabr...@usosim.com.br> wrote:
> Eu to sem tempo pra olhar agora, mas fim de semana eu dou uma garimpada.
> Sei que existem métodos que não tem documentação alguma, e nenhum
> atributo é documentado em lugar algum.
>
> 2009/12/17 Marcelo Andrade <mfandr...@gmail.com>:
>
>
>
> > 2009/12/17 Gabriel Gilini <gabr...@usosim.com.br>:
> >> Sinceramente o que faz falta é a boa documentação dos métodos e
> >> atributos. Não tenho nada contra o formato da API, mas sim com o
> >> conteúdo.
> >> O Nate disse outro dia que eles erraram feio em não ter documentado no
> >> código decentemente desde o começo, e isso atrasou muito o processo de
> >> gerar uma documentação decente pro Cake. Se tudo fosse muito bem
> >> explicado e contivesse exemplos de uso, não haveria problema algum na
> >> minha visão.
>
> > Mas o que EXATAMENTE? Qual método que tentaste usar
> > e tiveste dificuldade por conta da API? E como tu achas que
> > poderia melhorar?
>
> > Atts.
>
> > --
> > MARCELO F ANDRADE
> > Belem, Amazonia, Brazil
>
> > "I took the red pill"
>
> > --
>
> > Recebeu esta mensagem porque está inscrito no grupo "CakePHP Tuga" dos Grupos do Google.
>
> > Para publicar uma mensagem neste grupo, envie um e-mail para cakep...@googlegroups.com.
> > Para anular a inscrição neste grupo, envie um e-mail para cakephp-pt+...@googlegroups.com.
> > Para ver mais opções, visite este grupo emhttp://groups.google.com/group/cakephp-pt?hl=pt-PT.
>
> --
> Gabriel Gilini
>
> www.usosim.com.br
> gabr...@usosim.com.br
Gabriel Gilini
> Eu vejo duas alternativas melhores que o site da API:
> 1) Use uma IDE que leia os comentários de Doc, assim você estará
> usando a API exata para sua aplicação.
Mas a API online é gerada exatamente pelos comentários.
> 2) Leia o código fonte do cake. Lá você encontra o que precisa e as
> vezes mais. Além disso, consegue ver qual a lógica estão utilizando,
> para ver se realmente é aquilo que você queria que fosse feito.
Sim, isso funciona muito bem, mas toma muito tempo. A documentação foi
inventada justamente para que você não precise ler o código e entender
toda a lógica. Imagine se você precisasse ler o código da STL pra usar
um std::map<> em C++.
> Para ver mais opções, visite este grupo em http://groups.google.com/group/cakephp-pt?hl=pt-PT.
>
>
>
--
Gabriel Gilini
Juan Basso
estar vendo uma API na internet que seja desatualizada ou não seja a
mesma versão que você está trabalhando.
Acho que a API é só uma referência rápida e não uma documentação. Para
saber como os métodos funcionam e que parâmetros devem ser passados,
você deve ler o book.
Acho legal ler o código fonte das aplicações porque elas explicam
melhor que os breves comentários que colocam ali ou a documentação que
não é tudo aquilo. E outra, depois que você começa a ler os fontes,
tudo fica mais claro e você não vai precisar ficar consultando
novamente a API/Book/Fontes.
Uma analogia, se você conhece de carro, quando você ouvir um barulho
estranho você já vai saber o que é, não precisa consultar um mecânico
ou manual...
Juan Basso
On 18 dez, 07:30, Gabriel Gilini <gabr...@usosim.com.br> wrote:
> 2009/12/18 Juan Basso <jrba...@gmail.com>:
Zé Carlos
Na minha opinião, documentação deverá ser o book, com exemplos de utilização, técnicas e dicas.
2009/12/18 Juan Basso <jrb...@gmail.com>
Cauan Cabral
Porém ela deve ser um local onde você pode consultar a assinatura de um método, atributo de um classe
e alguma descrição útil para a função de cada classe/método/atributo. E nisso a API falha. Na minha opinião o maior problema da API
não é sua organização, mas a falta de comentários no código que é usado para gera-la, o que implica na falta de conteúdo
da API.
Acho que para ajudar a melhorar a API, só fazendo um trabalho de refatoração do framework, inserindo comentário em todas as partes
do mesmo. Porém, acho que isso é acessível apenas para os desenvolvedores do CORE, correto? Não sei como poderíamos ajudar nisso
(se é que há interesse do grupo nisso).
Também acho que o Book precisa ser expandido, é preciso atualizar informações, adicionar mais exemplos, novas aplicações práticas. E essa
parte do Book deve sim ser voltada para os "novatos".
Só citando um caso pessoal, quando optei por trabalhar com o CakePHP, um dos principais motivos foi a documentação dele, que achei acessível
e, até certo ponto suficiente. Hoje, já enxergo ela como defasada, até em relação aos outros grandes frameworks PHP, principalmente quando passo
ela para um "novato" estudar.
Concluindo, acho que a API e o Book são extremamente importantes, cado um para seu objetivo porém ambos estão parados, precisam de atenção.
Olhar código fonte para entender uma implementação é ótimo, te da um outro nível de abstração, porém obrigar desenvolvedores que estão iniciando no
framework a fazer isso é dar um tiro no próprio pé, a não ser que o objetivo do framework seja atender apenas "escovadores de bits".
---------------------
Google Talk: 
Skype: CauanCabral 
MSN: 
Marcelo Andrade
Só ratificando de novo. Gostaria de objetivar a discussão. Se a API não é
perfeita (e ninguém está dizendo que é), o que poderíamos fazer nós mesmos
para melhorar? Então vão lá umas perguntas:
1) Faltam exemplos de utilização de código na API, sim ou não? O que
gostaríamos que tivesse? Quem tiver tido uma dificuldade com algo e acha
que ajudaria ter um exemplo de código, compartilhe pra gente sugerir ou
tentar bolar algo.
2) A API deve ser o mais completa e extensa possível ou o mais sintética e
resumida possível? É pra ser uma referência geral ou mais um recurso para
iniciantes? Ou não dá pra ser as duas coisas? Teria que haver um guia
básico e um guia avançado de CakePHP?
3) Falta traduzir a API para português? (Essa me ocorreu agora :-)
Relendo a mensagem do Gabriel, lembrei que logo no comecinho tive alguma
breve dificuldade com o find, porque se você olhar no cookbook e na API sem
muita atenção, dá a entender que são duas assinaturas e dois métodos
diferentes.
cookbook [1]:
find($type, $params)
API [2]:
find($conditions= NULL, $fields= array ( ), $order= NULL, $recursive= NULL)
Principalmente para quem está começando ou ainda não conhece muito bem
como PHP funciona (no caso, a sobrecarga de parâmetros), entendo que isso
pode ser bem confuso.
Mas na verdade, apesar de na API o primeiro parâmetro $conditions ser um
array, ela ainda diz que pode ser uma string para usar as novas notações do
find. No caso, eu nunca uso find sem dizer o tipo na frente, e pra mim a
forma explicada no book é mais simples e fácil de entender.
[1] http://book.cakephp.org/pt/view/449/find
[2] http://api.cakephp.org/class/model#method-Modelfind
Então arriscaria dizer que o cookbook é o local mais indicado para se começar.
E quando você quiser sair do básico para o avançado, a API é que deve lhe
ajudar.
2009/12/18 Cauan Cabral <cau...@gmail.com>
>
> Porém ela deve ser um local onde você pode consultar a assinatura de um método, atributo de um classe
> e alguma descrição útil para a função de cada classe/método/atributo. E nisso a API falha. Na minha opinião o maior problema da API
> não é sua organização, mas a falta de comentários no código que é usado para gera-la, o que implica na falta de conteúdo
> da API.
Pois é. O que queria era mapear exatamente pontos como esses que você falou em
que a API falha. Quem sabe para não bolarmos um esforço de aprimoramento da
API ou mesmo sugerir pra galera do core.
> Acho que para ajudar a melhorar a API, só fazendo um trabalho de refatoração do framework, inserindo comentário em todas as partes
> do mesmo.
Entendo teu ponto de vista, mas... só refatorando todo o framework para
termos uma boa documentação? Hum... Nesse caso acho difícil termos
isso antes da versão 2.0, que talvez seja o marco mais próximo onde uma
refatoração geral possa ocorrer.
> Porém, acho que isso é acessível apenas para os desenvolvedores do CORE, correto? Não sei como poderíamos ajudar nisso
> (se é que há interesse do grupo nisso).
Por que não? Por que não montar uma equipe de documentação do
CakePHP? Acho que bons frameworks certamente têm equipes dedicadas
apenas à parte de documentação. Não sei direito como isso é no Cake,
mas acho que no fim das contas deve tudo acabar apenas na mão do
AD7six.
> Também acho que o Book precisa ser expandido, é preciso atualizar informações, adicionar mais exemplos, novas aplicações práticas. E essa
> parte do Book deve sim ser voltada para os "novatos".
É isso que devemos ter em mente. O book é livre! Qualquer um de
nós pode sugerir alterações, novas seções, etc. Se a gente conseguir
definir o que realmente a gente acha que falta, um checklist mesmo,
podíamos ao menos fazer um esqueleto que fosse sendo expandido e
melhorado com o tempo.
É isso.