doc_down: todo list

[Morriar]

Pre-processing:

• [x] autolink "http://"
• [ ] autolink model entities, namespaces, signature etc
• [ ] autolink pages and sections

Checking:

• [ ] spell checker
• [ ] style: indent, uppercase at the begining of the synopsys and a dot at the end...
• [ ] synopsys length
• [ ] ref checking: check reference like foo Bar::foo, also check visibility of the target
• [x] code checking: compile and try code examples.
• [ ] annotations: lowercase warning, annotation name...

Plus:

• [ ] warn on complex undocumented method: select some SE metrics that mark a method/class/module as "complex" and check if a documentation is associated
• [ ] suggest links: model or static analysis to find highly coupled method and propose a SEE: link

[privat]

Synopsis trop (combien?) long.

[Morriar]

Configurable via option avec un default. Étant donnée la largeur des nouveaux écrans j'irais jusqu'à 100 max 110.

Fun facts:

• Java suggère 80 chars. Après ça change en fonction des projets:
  • Android impose 100 avec quelques exceptions
  • Maven impose 120 chars
• Python semble avoir une limite à 79 chars mais la ref date.
• Chez Ruby on Rails rien n'est précisé. Mais bon on sait que les codeurs ruby sont des hippies :)
• Zend (les gars de PHP) fixe une limite dure à 120 chars mais préfère le 80
• pear recommande entre 75-85

Bref y'a pas vraiment de recette magique.

Pourquoi je dis entre 100 et 110 alors?

• Github utilise des boites de code fixées à 114 chars de largeur.
• Ma résolution (pas si ridicule que ça quand même) me permet 100 chars de long si je travaille en splitté vertical.

D'ailleurs j'aime beaucoup cet article qui se demande si la limite à 80 a encore du sens. Quelques remarques intéressantes qui en sont issues:

An 80 character limit has no relevance any more with modern computer displays. [...] If you write code 80 columns wide, you can relax knowing that your code will be readable and maintainable on more-or-less any computer in the world. Another nice side effect is that snippets of narrow code are much easier to embed into documents or blog posts. [...] C (ndlr: nit aussi) generally has much shorter identifier names, and subsequently much shorter lines than, say, a .NET language. [...] For open-source projects, or other situations where you don’t know who’s going to be reading your source code, tradition dictates that you stick with 80.