Yes, those things can happen, but I think they can all be handled without big troubles. Note that Rich Morin specifically mentioned using something like codeq to notice when particular functions change, and thus their documentation bears re-examining. diff also works, at a file granularity rather than function granularity.
In general, what happens when the code changes is that someone eventually notices, preferably with a bit of automation to help them notice, and then goes and does the manual work required to update the docs if necessary. For something like Clojure and its contrib libraries, the target is moving slowly enough that it can be kept in your targeting sights without much trouble :-) Clojure has had approximately one release per year, and the behavior of most functions hasn't changed. For other non-core libraries where new releases come out more often, the default can be to populate the new version of documentation the same as the previous version, and then look for changes where needed. Then again, for some of those non-core libraries, the doc strings are already quite extensive and the enhanced-docstrings idea might not be desirable for them. Andy On Jan 21, 2013, at 11:15 PM, Korny Sietsma wrote: > The flip side, of course, is that having documentation separate from code > often leads to the documentation becoming out of sync with the code. > > What happens when someone renames or moves some code, but doesn't also move > the docs? What happens if they change the implementation? Will people > remember that every code change might potentially also require a change to > documentation, stored somewhere else, and potentially versioned independently? > > - Korny -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en
