Wiki - Documentação about validation HOT 24 CLOSED

Eu tinha pensado em manter junto ao respect.github.com

Algo como respect.github.com/validation.html
--> Mostraria o básico (instalação, testes, usando namespace, validação simples, encadeada....)

E algo como respect.github.com/validation/rules.html
--> Mostraria cada regra, em ordem alfabética, com usos e exemplos, num estilo como esse (http://www.habitare.com.br/faq/).

Defendo menos arquivos, pois ficará mais fácil de manter e alterar.

from validation.

Existe também a opção de manter a documentação nos próprios repositórios de cada projeto.

Eu particularmente gosto da idéia do Wiki porque qualquer um de fora do projeto pode alterar mesmo sem permissões, e isso pode se tornar útil depois. Cada Wiki no Github também é um repositório git, o que torna manutenção e qualquer tipo de automação simples.

Existe também uma diferença entre a documentação da API, guias, tutoriais, manuais, etc. Não tenho muito conhecimento sobre isso, provavelmente temos que buscar referências sobre a organização dessas sessões em outros projetos!

from validation.

Manter a documentação no repositório eu acho complicado, porque escrever a documentação em html sem nenhum WYSIWYG pode se tornar uma tarefa bem entediante.

Sobre a organização, acredito que a melhor forma seria uma padronização dos títulos das páginas. ex:

Rules / Numeric ou Api / Rules / Numeric
Tutorials / Getting Started
About / How to Contribute ou Validation / How to Contribute ou somente How to Contribute

E na página principal lista de maneira organizada os links da documentação. ex:

API

Numeric
foo
bar

Tutorials

Getting Started
foo
bar

e por ai vai =)

from validation.

Olá pessoal, pretendo ajudar a escrever a documentação e comecei a fazer alguns exemplos, vejam abaixo:

v::noWhitespace()->validate('Respect'); //return true
v::noWhitespace()->validate('Respect Validator'); //return false
v::noWhitespace()->validate('1010'); //return true
v::noWhitespace()->validate('10 10'); //return false

Eu estou sendo muito especifico ou basta apenas um exemplo que retorna true e outro que retorna false? Nesse caso queria mostra que funciona também com números, mas é uma informação meio obvia, concordam?

Quero fazer exemplos para todas as regras, alguém já esta fazendo isso?

from validation.

Tem um exemplo pra cada regra no README e há também os testes de cada regra que possuem exemplos muito bons de como o validador se comporta.

Além do validate(), existe o check() e o assert() que disparam exceções com mensagens de erro. Na classe de cada validador, existem as mensagens que esse validador retorna. Também é legal documentar isso de alguma forma.

Também vale a pena mencionar em cada página da documentação que o import use Respect\Validation\Validator as v é necessário para utilizar o prefixo v::.

No mais, achei os exemplos do noWhitespace legais e bem explicativos. Se não me engano ele também não aceita quebras de linha e tabs, seria legal demonstrar isso =D

from validation.

E será feito na wiki ou no respect.github.com?

from validation.

Eu prefiro na Wiki, vai simplificar a manutenção.

from validation.

Eu fiz uma página na wiki só p/ exemplo https://github.com/Respect/Validation/wiki/Rules---Alpha, gostaria de saber a opinião de vocês..

from validation.

@allmeida eu to mexendo na página que vc fez! Já já comento sobre ela.

from validation.

Acho que as sessões de Properties e Methods podem ser omitidas. Todos os validadores implementam o mesmo set de métodos (validate(), check() e assert()). A idéia é fazer um manual com algo bem simples e descritivo.

Editei o exemplo que você fez com algumas alterações! Também notei que ele removeu o "/" to título, então mudei o formato pra Rule. Portanto, Alpha Rule nesse caso.

https://github.com/Respect/Validation/wiki/Alpha-Rule

O ideal é que o manual de cada regra seja composto de N casos de uso, sendo obrigatório pelo menos o Basic Usage em primeiro lugar, que descreve o funcionamento mais simples possível e a lista de mensagens de validação que a exceção dessa regra pode disparar.

from validation.

Ótimo @alganet, deste modo realmente ficou bem melhor!
Sobre o "/" é que a wiki do github não aceita/mostra este carácter...
Vou dar uma alterada na página Rules e na Home...

from validation.

Adicionei o manual para a regra Almun https://github.com/Respect/Validation/wiki/Alnum-Rule

Eu não coloquei que poderia ser combinado com outras regras, acho que ficaria melhor se tivesse uma pagina especifica com exemplo de combinações, o que acham?

from validation.

Seria interessante se cada um fosse adicionando o link na página Rules da Wiki e que ao fim de cada página houvesse um link Voltar, que apontaria pra Rules.

O que acham?

from validation.

@EduardoLopes acho que algumas combinações óbvias fazem sentido. Por exemplo, essa dos caracteres alfanuméricos+noWhitespace (que faz sentido pro Alnum, Alpha e Digits).

Outro exemplo seria a regra Length ou a regra Between, que trabalham com vários tipos de dados. Utilizar ela sem utilizar uma checagem por tipo (estilo Arr, Date ou String) é um problema de segurança em potencial e devemos evidenciar isso de alguma maneira.

@jeanpimentel acho legal a idéia do voltar. Talvez "Back to the Rule list" seja um bom nome. Aceito sugestões!

from validation.

Sobre a pag Rules, eu estou adicionando os links, e estou separando por "categoria" como Numeric, String, Array, etc.
Eu não acho o link de voltar necessário, mas não vejo problema em adiciona-lo.

@EduardoLopes acho que seria melhor colocar pelo menos um exemplo, e dai indicasse para uma página especifica, para caso quiserem saber mais sobre o assunto.

from validation.

@allmeida Atualizei a home e coloquei os links das duas regras na pagina rules, não pensei que você estivesse fazendo isso agora :)

from validation.

Eu atualizei a pagina Rules, quem puder dar uma revisada fico agradecido =)

from validation.

@alganet deixa eu ver se entendi: Então as combinações mais obvias podem ficar em outra pagina. E alertar sobre as regras que precisam de uma validação a mais, assim mostrando um exemplo na pagina da regra?

from validation.

@EduardoLopes sim, é praticamente isso!

from validation.

Adicionei mais algumas paginas às regras. Por favor revisem para ver se eu esqueci de algo, e também porque meu inglês não é dos melhores. :)

Também acho que encontrei um bug, não sei exatamente o que devo fazer, abro um 'issue'?

from validation.

Darei uma revisada, @EduardoLopes! Obrigado por contribuir =D

Quanto ao bug, o melhor é abrir uma issue mesmo.

from validation.

Eu tô revisando e achei algumas coisas que acho legal mencionar:

• É interessante sempre usar exemplos próximos de casos reais de validação, não apenas coisas aleatórias.
• Na descrição de cada validador, estou tentando dar exemplos de cenários nos quais eles poderiam ser utilizados.
• Combinações de validadores são interessantes de manter na página de cada regra, mesmo que elas sejam redundantes e repitam-se entre páginas. (Aliás, me desculpem se em algum momento eu não deixei esse assunto claro).
• Só deve haver um exemplo de cada cenário. Não há motivo pra mostrar 10 exemplos de inteiros válidos, um é suficiente. O importante é tentar identificar cada cenário.

from validation.

Adicionei ouras paginas, eu tentei pensar em exemplos onde as regras poderiam ser usadas e não consegui pensar em nada bom. Min ou max por exemplo, poderia validar idade, mas já tem uma regra especifica para isso (que eu não sei exatamente como usar, aliás).

Vejam se eu consegui explicar direito como funciona a regra Between.

Mais tarde farei mais coisas.

from validation.

Estou considerando essa Issue fechada, já que definimos um modelo legal de documentação! Agradeço a todos que colaboraram! Muito obrigado =D

from validation.