On Thu, 2002-10-24 at 07:18, Stefan Schwarzer wrote: > > Actually, I guess my real issue is that inline documentation doesn't > > distinguish between user interfaces and internal interfaces -- > > particularly when those internal interfaces are not entirely internal, > > like methods that you may wish to override in a subclass, but which you > > wouldn't call directly. > > I share your objections on doing all documentation via docstrings. I > also sometimes find myself struggling on whether I should rely only on > docstrings (because it's convenient and doesn't afford to write some > things twice) or not (because of the reasons you mentioned). In my > opinion, it's better to have extra documentation besides the > docstrings and as a user of Webware I would prefer to have the extra > documentation. Additionally, even (potential) developers would be > better off with starting with overviews and _then_ reading source > code/docstrings. Then, attracting more users which eventually become > contributors might make the further development of Webware easier.
Hmm... I just thought about a compromise between docstrings and external documentation -- at least for certain classes/modules, we could put the relevant documentation in the docstring for the module. This gives us freedom to structure it however we want, but more importantly it makes it easy to keep that documentation up to date as the module changes. We could also include references to any external documentation that may need to be updated along with it. There's still a lot of other documentation we'd need -- but this can cover things like Page, HTTPRequest/Response, Session, and maybe some other stuff. Potentially we can leave a lot of the reference documentation in this docstring form, and allude to it in other documentation (where we'd only introduce the most common usage). Ian ------------------------------------------------------- This sf.net email is sponsored by: Influence the future of Java(TM) technology. Join the Java Community Process(SM) (JCP(SM)) program now. http://ads.sourceforge.net/cgi-bin/redirect.pl?sunm0003en _______________________________________________ Webware-devel mailing list [EMAIL PROTECTED] https://lists.sourceforge.net/lists/listinfo/webware-devel
