It is actually detailed, just look at the source code of UIComponent as an exmaple, the class documentation alone is 134 lines long!! When I read the source code I generally only look at the first lines of the documentation to have general idea. If I need more details I read the generated HTML documentation which is much easier to read.
Haykel On 16 February 2012 15:56, almansour belleh blanco <zabouzamomo...@gmail.com > wrote: > Well, it is not really detailed documentation. It's a documentation > generated > automatically and for that you have just to follow a common procedure > for writing > the comments. It is useful so that when your code is read by other > developers, it can > be better understood. > > > > 2012/2/16 Haykel BEN JEMIA <hayke...@gmail.com>: > > Personally I never write detailed documentation while developing. I > > generally write a short description and the detailed documentation is > > either written by someone else or in another documentation pass, which > can > > be done in other files. > > > > I have suggested stub classes in an earlier e-mail because I think this > > could be useful also for IDEs. They would not require the whole source > code > > for auto-completion, documentation etc. > > > > Haykel > > > > > > > > > > On 16 February 2012 14:41, Carol Frampton <cfram...@adobe.com> wrote: > > > >> I am totally against stripping out the asdoc. Who do you think writes > the > >> asdoc? We do. It is just as important as the code. If you strip it > out > >> it won't be kept current. It should be part of any code review. > >> > >> Carol > >> > >> On 2/16/12 4 :15AM, "Omar Gonzalez" <omarg.develo...@gmail.com> wrote: > >> > >> >> > >> >> Perhaps a script to strip out all comments and a way to create > patches > >> >> ignoring missing comments would be useful? > >> >> > >> >> Thanks, > >> >> Justin > >> > > >> > > >> >I'm not quire sure what you mean. The ideal solution would be to figure > >> >out > >> >a way to keep comments in such a way that the during development > they're > >> >not in our files but at release or at patch submission the proper > >> >documentation is there. > >> > > >> >-- > >> >Omar Gonzalez > >> >s9tpep...@apache.org > >> > >> > > > > -- > Mansour Blanco > Software engineer > Stackoverflow: http://stackoverflow.com/users/612920/mansuro > Blog: zuro.blogspot.com > github: https://github.com/Mansuro >
