Comments (24)
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
Tutorials
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.
Related Issues (20)
- ctype_digit deprecation notice HOT 1
- Release 2.2.4 HOT 2
- Roadmap to 2.3 HOT 13
- Code coverage in local environment HOT 2
- [documentaiton] Validation for a full array of data HOT 3
- Formatter inconsequently stringifies values HOT 6
- IBAN Validation with non-breaking spaces HOT 1
- How do custom validation rules throw custom error messages? HOT 2
- How to compare two field HOT 1
- DateTime validation fails on valid ISO-8601 timestamp HOT 1
- phone() validation incorrectly invalidates valid UK phone numbers HOT 2
- phone() in 2.3 dont work correctly HOT 13
- RFC 3339 Z suffix no longer works with date-time validation in 2.3 HOT 16
- Date-related rules are not working today HOT 3
- Unexpected behavior with the country code rule in 2.3 HOT 4
- Roadmap to 3.0
- Increase code coverage HOT 3
- Email validation with accented characters HOT 3
- Why is it mandatory to require the PHP version to be so new? HOT 2
- DateDiff rule HOT 8
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from validation.