On 1 Jul 2010, at 10:04, Quentin Mathé wrote: > Having arbitary views constructed on-demand to edit the code makes > sense. We can build this kind of UI views if the IDE has access to the > AST and hides/shows some parts of the AST. But if the IDE is that > flexible, then whether the API documentation is embedded in the code > or stored separately doesn't really matter I think.
The point is that, for frameworks written in Objective-C, you will not have the source code in the framework (Actually, that's something else I'd like to fix, but it's another issue). In CodeMonkey, you should just be able to select any class / method and have it display the docs, irrespective of whether they are from the current project or from a framework. > It's probably a bit harder to store the API doc in XML, since there is > a need to update the XML when methods/classes/vars are moved/inserted/ > removed. The synchronization need could be minimized with a XML format > where every methods/classes/vars are identified by UUID, but then this > XML would be harder to edit directly. I'm not sure that I understand the problem. We have two cases: In the Objective-C case, we have files. These files contain some source code and some doc comments. The headers are parsed and the doc comments are extracted and put into the XML. No synchronization required - you just regenerate them as required. In the Smalltalk case, we have an IDE (and files, but they're an implementation issue). The docs are updated when you modify a method in the IDE. > The other downside I see is that you cannot edit the Smalltalk code > directly (without CodeMonkey), otherwise the doc becomes outdated e.g. > If a method is renamed, you have no easy way to detect what to updates > in the XML the next time you run CodeMonkey. It's probably easy to > detect the renaming of a single method but when multiple renaming > occurs it is going to be impossible (unless we leverage the CoreObject > history but that sounds really complex when there is no need to). Yes, that would be true. Of course, we could use some kind of weave thing when exporting from CodeMonkey, so that we have the docs and everything else in the same file. Ideally I'd like to use EtoileText for the documentation, so we'd be storing an EtoileText tree internally, and just exporting it as XML for interfacing with other things. >> the XML is more useful for tools, the HTML more useful for humans (and >> we can generate the HTML ...). If we have to choose one, use the XML, >> otherwise put both ? > > I agree it's probably worth to package both. That would use up a bit more space, but it might be worth doing. Of course, the HTML is only useful once we have a web browser - we could have a documentation browser that reads the XML in installed frameworks quite easily now. David -- Sent from my brain _______________________________________________ Etoile-dev mailing list Etoile-dev@gna.org https://mail.gna.org/listinfo/etoile-dev
