Hi,
I am in a need of documenting a library. However, I can't seem to decide what approach to take. I think the most important thing for me is that the documentation (API doc) is up-to-date, always and that it is very helpful (e.g. provides sample codes and has plenty of description). However, is it a problem if my source code is full of doc-tags? I am writing JavaScript if that matters and there is going to be a production version that is trimmed down though.
I looked into ExtJS, and it seems that they are having loads of HTML inside their source files. I think it makes it easy to keep the documentation up-to-date, and that it's harder to forget documenting a feature. However, this just looks so ugly -- am I the only one?