Le 9 juil. 2010 à 10:45, David Chisnall a écrit : > 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.
I agree that embedding the source code would be nice too. For the doc generator started by Nicolas and on which I have been working on recently, it should be easy to support various parser based on the file type. For example, if the input file is a .gsdoc file, we use the built-in parser, if it's a .st file, we use the related LanguageKit parser and in the long run, we could also use the Clang parser for .h .m files. >> 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. I shouldn't have started the next paragraph with 'The other downside' but 'The downside', since it illustrates the problem I mention above. >> 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. Yes. Nicolas' doc generator has a tree structure representation with various kinds of nodes like Method, Function, Class, Doc Page, Page Header etc. Once EtoileText is fully mature, a way to integrate both is to turn these node class into subclasses of the EtoileText tree node class, better approaches might exist though. Cheers, Quentin. _______________________________________________ Etoile-dev mailing list Etoile-dev@gna.org https://mail.gna.org/listinfo/etoile-dev
