From dave at badgers-in-foil.co.uk Sat Jan 1 18:33:56 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Sat, 1 Jan 2005 18:33:56 +0000 Subject: [as2api-dev] doc generation does not work with 0.2 gui windoes version In-Reply-To: <002401c4eeb5$3cbf2e70$07affea9@simon> References: <002401c4eeb5$3cbf2e70$07affea9@simon> Message-ID: <20050101183356.GA29056@vhost.badgers-in-foil.co.uk> On Thu, Dec 30, 2004 at 10:19:24PM +0100, Simon Wacker wrote: > Hi Guys, > > I tried to generate the documentation for the as2lib with the 0.2 gui > version for windows, but the generation tool just closes itself and > does nothing when I press the Generate Docs button. I have both added > the class path and the output target. > The generation worked just fine with the 0.1 version. > Any ideas how this could be finxed or what's causing that strange behaviour? Oops. It appears I didn't build the exe-file correctly. I'll post a corrected version as soon as possible, and let you know. thanks for pointing out the problem! dave -- http://david.holroyd.me.uk/ From dave at badgers-in-foil.co.uk Sun Jan 2 00:44:42 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Sun, 2 Jan 2005 00:44:42 +0000 Subject: [as2api-dev] doc generation does not work with 0.2 gui windoes version In-Reply-To: <20050101183356.GA29056@vhost.badgers-in-foil.co.uk> References: <002401c4eeb5$3cbf2e70$07affea9@simon> <20050101183356.GA29056@vhost.badgers-in-foil.co.uk> Message-ID: <20050102004442.GA1466@vhost.badgers-in-foil.co.uk> On Sat, Jan 01, 2005 at 06:33:56PM +0000, David Holroyd wrote: > On Thu, Dec 30, 2004 at 10:19:24PM +0100, Simon Wacker wrote: > > I tried to generate the documentation for the as2lib with the 0.2 gui > > version for windows, but the generation tool just closes itself and > > does nothing when I press the Generate Docs button. I have both added > > the class path and the output target. > Oops. It appears I didn't build the exe-file correctly. I'll post a > corrected version as soon as possible, and let you know. I've put an updated version of the windows zip onto the site, http://www.badgers-in-foil.co.uk/projects/as2api/releases/as2api-allinone-w32-0.2.zip (Just to make sure you have the correct version; the updated as2api_win32.exe this contains is 5,984,282 bytes, and the old one is 5,980,307 bytes.) I hope this one will work! Sorry for the inconvenience. dave -- http://david.holroyd.me.uk/ From dave at badgers-in-foil.co.uk Fri Jan 7 11:14:17 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Fri, 7 Jan 2005 11:14:17 +0000 Subject: [as2api-dev] Nomenclatures for doc generation In-Reply-To: References: <002401c4eeb5$3cbf2e70$07affea9@simon> <20050101183356.GA29056@vhost.badgers-in-foil.co.uk> <8341FAA0-5C27-11D9-9DD2-000A95A67B22@ifrance.com> <20050102225435.GA19232@vhost.badgers-in-foil.co.uk> Message-ID: <20050107111417.GA13436@vhost.badgers-in-foil.co.uk> --1yeeQ81UyVL57Vl7 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline On Wed, Jan 05, 2005 at 10:00:36PM +0100, erixtekila wrote: > >>Could you send a list of supported keywords ? > > > >@param is supported, as long as the parameter names actually match > >formal parameters of the function, > > > > /** > > * @param foo must not be null > > * @param blat will not appear; it doesn't match a real paraemter! > > */ > > public function getThingy(foo, bar) > ?And as long as it is formatted like : > *@paramfooComment. > > Unfotunatly, I used to format my comment like this for the sake of > clarity : > *@paramfooComment. Oops! Thanks for pointing that out -- the parser does indeed require a single space after each 'at-tag', and this is incorrect. I attach a patch to doc_comment.rb that corrects this. > >@return is supported: > > > > /** > > * Generate another identifier > > * @return an integer>=1, or null if no Id is available > > */ > > public function nextId() { ... > I can't make @return work here? This may be the above whitespace issue again. > >@throws is supported, but the class-name isn't hyperlinked yet: > > > > /** > > * @throws NoSuchElementException if the given key is missing > > */ > > public function getValue(key) { ... > I haven't test? > > > >@see is semi-suppported. However the contents of the tag are just > >copied into the resulting HTML, no links are created (as in javadoc) > >yet: > > > > /** > > * @see documents located elsewhere > > */ > > class FooBar { ... > > > I can't make @return work here? Well, you shouldn't be able to have @return for a class anyway. If you meant that @see doesn't work, then maybe, again, it's a problem with whitespace? > >In all cases, the tags above *must* appear as the first item on a new > >line after the description (leading '*'s and whitespace are allowed). > Does that mean that the foolowing can't work ? Because of the multiple > @tags ? > /** > * Ajoute un nouvel observateur. > * > * @param listener R?f?rence de l'observateur. > * @return Un bool?en indiquant la r?ussite de l'op?ration. > * @see A class. > */ Multiple tags *should* be allowed, even by the current code. What I was trying to emphasise was that writing the tags like this will not work: /** * A description of the method's interface, avoiding unnecessary * description of its implementation. @see #otherMethod() which * is effected by calling this method. @return some result; * guaranteed non-null. */ The parser will not pick these up because each tag must be a new paragraph (so the example you give above is perfectly fine). I hope this fixes things for you, dave --1yeeQ81UyVL57Vl7 Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="attag_whitespace-patch1.diff" Index: doc_comment.rb =================================================================== --- doc_comment.rb (revision 54) +++ doc_comment.rb (working copy) @@ -45,18 +45,18 @@ text = strip_stars(text) unless text =~ /^\s*$/ case text - when /^\s*@param ([^ ]+)/ + when /^\s*@param\s+([^\s]+)/ state = :PARAM desc_param = $' add_param($1, desc_param) - when /^\s*@return / + when /^\s*@return\s+/ state = :RETURN desc_return = $' - when /^\s*@see / + when /^\s*@see\s+/ state = :SEE seealso = $' add_seealso(seealso) - when /^\s*@throws ([^ ]+)/ + when /^\s*@throws\s+([^\s]+)/ state = :THROWS desc_throws = $' add_exception($1, desc_throws) --1yeeQ81UyVL57Vl7-- From dave at badgers-in-foil.co.uk Fri Jan 7 17:51:57 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Fri, 7 Jan 2005 17:51:57 +0000 Subject: [as2api-dev] Nomenclatures for doc generation In-Reply-To: <3AC90BE8-60CF-11D9-B3B9-000A95A67B22@ifrance.com> References: <002401c4eeb5$3cbf2e70$07affea9@simon> <20050101183356.GA29056@vhost.badgers-in-foil.co.uk> <8341FAA0-5C27-11D9-9DD2-000A95A67B22@ifrance.com> <20050102225435.GA19232@vhost.badgers-in-foil.co.uk> <20050107111417.GA13436@vhost.badgers-in-foil.co.uk> <3AC90BE8-60CF-11D9-B3B9-000A95A67B22@ifrance.com> Message-ID: <20050107175156.GA18743@vhost.badgers-in-foil.co.uk> On Fri, Jan 07, 2005 at 06:11:54PM +0100, erixtekila wrote: > Thanks a lot, it's working better. > But the @return isn't generated at all in the html output. I'm very sorry; when I made that list of supported tags, I just reviewed the code that parses comments. I actually haven't implemented the code to output the captured text to the HTML. I will try to do this for you soon! > I've discover also that the link in the html for "Overview" misses the > "apidoc" repertory level. > Same for references of classes inside other class docs. > So the url just don't work. I saw this in the documentation you forwarded the other day. I don't see this when I generate documentation locally though, so could you show an example of how you invoke the script on the command line? I suspect there might be a bug when relative paths are used, or something like that. dave From dave at badgers-in-foil.co.uk Sat Jan 8 11:09:45 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Sat, 8 Jan 2005 11:09:45 +0000 Subject: [as2api-dev] Nomenclatures for doc generation : "$" forbidden ? In-Reply-To: <5D5CD618-60FD-11D9-B3B9-000A95A67B22@ifrance.com> References: <002401c4eeb5$3cbf2e70$07affea9@simon> <20050101183356.GA29056@vhost.badgers-in-foil.co.uk> <8341FAA0-5C27-11D9-9DD2-000A95A67B22@ifrance.com> <20050102225435.GA19232@vhost.badgers-in-foil.co.uk> <20050107111417.GA13436@vhost.badgers-in-foil.co.uk> <3AC90BE8-60CF-11D9-B3B9-000A95A67B22@ifrance.com> <20050107175156.GA18743@vhost.badgers-in-foil.co.uk> <5D5CD618-60FD-11D9-B3B9-000A95A67B22@ifrance.com> Message-ID: <20050108110944.GA4316@vhost.badgers-in-foil.co.uk> --u3/rZRmxL6MmkK24 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline On Fri, Jan 07, 2005 at 11:42:09PM +0100, erixtekila wrote: > But i dig a little deeper and found that $broadcastMessage is not a > valid method name for as2api. > It generates error and refuses to output the entire class. The attached patch alters the lexer to allow a dollar to appear as either the first character, or any subsequent character of an identifier. This implies that syntax like this is correct: var $ = 1; function $() { ... } I've not verified if that's actually allowed by MM's compiler. FYI, I originaly based the lexer code on the ECMAScript specification. It turns out ActionScript 2 differs from ECMAScript a great deal, so there are likely to be more problems like this. A few more example files should shake them all out, though. dave --u3/rZRmxL6MmkK24 Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="allow_dollar_in_identifier-patch1.diff" Index: parse/lexer.rb =================================================================== --- parse/lexer.rb (revision 54) +++ parse/lexer.rb (working copy) @@ -253,8 +253,8 @@ nonascii = "[\\200-\\377]" unicode = "\\\\#{h}{1,6}[ \\t\\r\\n\\f]?" escape = "(?:#{unicode}|\\\\[ -~\\200-\\377])" - nmstart = "(?:[a-zA-Z_]|#{nonascii}|#{escape})" - nmchar = "(?:[a-zA-Z0-9_]|#{nonascii}|#{escape})" + nmstart = "(?:[a-zA-Z_$]|#{nonascii}|#{escape})" + nmchar = "(?:[a-zA-Z0-9_$]|#{nonascii}|#{escape})" SINGLE_LINE_COMMENT = "//([^\n\r]*)(?:\r\n|\r|\n)?" OMULTI_LINE_COMMENT = "/\\*" CMULTI_LINE_COMMENT = "\\*/" --u3/rZRmxL6MmkK24-- From dave at badgers-in-foil.co.uk Sat Jan 8 12:02:23 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Sat, 8 Jan 2005 12:02:23 +0000 Subject: [as2api-dev] Nomenclatures for doc generation : Relative path issue In-Reply-To: References: <002401c4eeb5$3cbf2e70$07affea9@simon> <20050101183356.GA29056@vhost.badgers-in-foil.co.uk> <8341FAA0-5C27-11D9-9DD2-000A95A67B22@ifrance.com> <20050102225435.GA19232@vhost.badgers-in-foil.co.uk> <20050107111417.GA13436@vhost.badgers-in-foil.co.uk> <3AC90BE8-60CF-11D9-B3B9-000A95A67B22@ifrance.com> <20050107175156.GA18743@vhost.badgers-in-foil.co.uk> Message-ID: <20050108120222.GC4316@vhost.badgers-in-foil.co.uk> Hi, On Fri, Jan 07, 2005 at 11:31:17PM +0100, viaContact wrote: > You were right about it : > >I suspect there might be a bug when relative paths are used, or > >something > >like that. > > I didn't remember but i've changed only one thing in your sources, the > last line of documenter.rb > > each_source(path) do |name| > File.open(File.join(path, name)) do |io| > begin > is_utf8 = detect_bom?(io) > print "Parsing #{path}:#{name.inspect}" > type = simple_parse(io) > type.input_filename = name > type.sourcepath_location(File.dirname(name)) > puts " -> #{type.qualified_name}" > type.source_utf8 = is_utf8 > type_agregator.add_type(type) > rescue =>e > $stderr.puts "#{name}: #{e.message}\n#{e.backtrace.join("\n")}" > end > end > end > > type_agregator.resolve_types > > # document_types("/home/dave/apidoc", type_agregator) > document_types("../apidoc", type_agregator) > > > Actually, that wasn't working for me with your absolute path? > So i've documented it. > But put a relative ../apidoc > > My fault, i didn't remember? sorry. No problem :) > What should i do ? > Only "apidoc" ? > I've tested like that and the classes references comes back. Hurrah ! "apidocs" is actually the text that I have in my current copy of the code. I think that should be reflected in the current distribution downloadable from the project page, too. > Another question. > I always work with utf-8 files. > I saw in html_output.rb, that you're searching for BOM. > Unfortunatly, it shouldn't be really accurate on my mac. > Because the intrepreter uses ISO instead. > Could there be a directive for the commandline ? By 'ISO', do you mean 'ISO Latin 1' encoding? If you always use UTF-8 encoding, what does an ISO encoding get used for? Do you mean that your UTF-8 files lack a byte-order marker? dave -- http://david.holroyd.me.uk/ From dave at badgers-in-foil.co.uk Tue Jan 11 01:01:00 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Tue, 11 Jan 2005 01:01:00 +0000 Subject: [as2api-dev] Some missing items Message-ID: <20050111010059.GB23491@vhost.badgers-in-foil.co.uk> I've committed to subversion some changes to have the HTML output code actually generate documentation for some of the the tags that where being collected, but not previously acted on. These where: - @return for method docs - @see for methods and fields (was already there for classes) dave -- http://david.holroyd.me.uk/ From dave at badgers-in-foil.co.uk Tue Jan 11 10:23:11 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Tue, 11 Jan 2005 10:23:11 +0000 Subject: [as2api-dev] Some missing items In-Reply-To: <412F65BE-63B7-11D9-BA74-000A95A67B22@v-i-a.net> References: <20050111010059.GB23491@vhost.badgers-in-foil.co.uk> <412F65BE-63B7-11D9-BA74-000A95A67B22@v-i-a.net> Message-ID: <20050111102311.GA32762@vhost.badgers-in-foil.co.uk> On Tue, Jan 11, 2005 at 10:57:50AM +0100, viaContact wrote: > Hi David, > > One question : > Could you give the url to the as2api svn repository. > That way i could checkout the MAIN trunk? > > Don't remember if you ever answer that question. I don't have the facility to give anonymous access directly to the SVN repository right now (mostly because I'm too lazy to upgrade to Apache 2). To collect my latest changes, you can use the ViewCVS interface mentioned on the project page. Specifically, you need to download these revisions: http://svn.badgers-in-foil.co.uk/viewcvs.cgi/*checkout*/as2api/trunk/as2api/html_output.rb?rev=59 http://svn.badgers-in-foil.co.uk/viewcvs.cgi/*checkout*/as2api/trunk/as2api/doc_comment.rb?rev=59 http://svn.badgers-in-foil.co.uk/viewcvs.cgi/*checkout*/as2api/trunk/as2api/api_loader.rb?rev=59 This is not very convenient, I know: I'll look into setting up an automated system to run nightly builds of the latest trunk version, and make these available for download on the project page. dave From viacontact at v-i-a.net Tue Jan 11 11:37:40 2005 From: viacontact at v-i-a.net (viaContact) Date: Tue, 11 Jan 2005 12:37:40 +0100 Subject: [as2api-dev] Some missing items In-Reply-To: <20050111102311.GA32762@vhost.badgers-in-foil.co.uk> References: <20050111010059.GB23491@vhost.badgers-in-foil.co.uk> <412F65BE-63B7-11D9-BA74-000A95A67B22@v-i-a.net> <20050111102311.GA32762@vhost.badgers-in-foil.co.uk> Message-ID: <334B5FCA-63C5-11D9-BA74-000A95A67B22@v-i-a.net> Nice, I've upgraded to the revision 59. I see that your enhancments works very well. Nice ! But shouldn't you give the direct url to the patches you made just =20 before : parse/lexer.rb Good work thanks. Le 11 janv. 05, =E0 11:23, David Holroyd a =E9crit : > On Tue, Jan 11, 2005 at 10:57:50AM +0100, viaContact wrote: >> Hi David, >> >> One question : >> Could you give the url to the as2api svn repository. >> That way i could checkout the MAIN trunk? >> >> Don't remember if you ever answer that question. > > I don't have the facility to give anonymous access directly to the SVN > repository right now (mostly because I'm too lazy to upgrade to > Apache 2). > > To collect my latest changes, you can use the ViewCVS interface > mentioned on the project page. Specifically, you need to download =20 > these > revisions: > > http://svn.badgers-in-foil.co.uk/viewcvs.cgi/*checkout*/as2api/trunk/=20= > as2api/html_output.rb?rev=3D59 > http://svn.badgers-in-foil.co.uk/viewcvs.cgi/*checkout*/as2api/trunk/=20= > as2api/doc_comment.rb?rev=3D59 > http://svn.badgers-in-foil.co.uk/viewcvs.cgi/*checkout*/as2api/trunk/=20= > as2api/api_loader.rb?rev=3D59 > > This is not very convenient, I know: I'll look into setting up an > automated system to run nightly builds of the latest trunk version, = and > make these available for download on the project page. > > > dave > > _______________________________________________ > as2api-dev mailing list > as2api-dev@lists.badgers-in-foil.co.uk > http://lists.badgers-in-foil.co.uk/mailman/listinfo/as2api-dev > _____________________________________________________________________ > > Envie de discuter gratuitement avec vos amis ? > T=E9l=E9chargez Yahoo! Messenger http://yahoo.ifrance.com > From dave at badgers-in-foil.co.uk Thu Jan 13 08:48:25 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Thu, 13 Jan 2005 08:48:25 +0000 Subject: [as2api-dev] Nomenclatures for doc generation : Relative path issue In-Reply-To: References: <20050102225435.GA19232@vhost.badgers-in-foil.co.uk> <20050107111417.GA13436@vhost.badgers-in-foil.co.uk> <3AC90BE8-60CF-11D9-B3B9-000A95A67B22@ifrance.com> <20050107175156.GA18743@vhost.badgers-in-foil.co.uk> <20050108120222.GC4316@vhost.badgers-in-foil.co.uk> <37E63690-617B-11D9-8556-000A95A67B22@v-i-a.net> <20050111003948.GA23491@vhost.badgers-in-foil.co.uk> Message-ID: <20050113084825.GA7817@vhost.badgers-in-foil.co.uk> On Wed, Jan 12, 2005 at 06:38:38PM +0100, erixtekila wrote: > Hi David, > > I've one request. > >That sounds very cool. It would be great to have a well documented, > >real-world example making use of as2api. I'd love to hear how you get > >on, and any other suggestions you come up with. > > Do you think it would be a false imlplementation of javadoc to add a > new @tag ? > IMHO, it misses @event that could tell what event some classes fires. > Since it's a big use in Flash EventDispatcher, i don't know how to > document those events ? > > In fact, one object (object or class) has to implement special event by > subscription. > This process is really obscure and **should** appear in docs. > > What do you think of ? > Is there another way ? > What do Java users use ? > > interface to implement for classes. > but how could we tell that an object fires events since he receive > subscription from another object at runtime ? I know that classes such as mx.containers.ScrollPane have class-attributes relating to events. I've no idea exactly what these do, but I suspect that annotating these attributes with documentation would be the best way to do what want. The syntax looks something like this: /** * ...event docs... */ [Event("foo")] /** * ...more event docs... */ [Event("bar")] /** * ...class docs... */ class pkg.Clazzname { ... } dave From dave at badgers-in-foil.co.uk Thu Jan 13 09:49:00 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Thu, 13 Jan 2005 09:49:00 +0000 Subject: [as2api-dev] Nomenclatures for doc generation : Relative path issue In-Reply-To: <20050113084825.GA7817@vhost.badgers-in-foil.co.uk> References: <20050107111417.GA13436@vhost.badgers-in-foil.co.uk> <3AC90BE8-60CF-11D9-B3B9-000A95A67B22@ifrance.com> <20050107175156.GA18743@vhost.badgers-in-foil.co.uk> <20050108120222.GC4316@vhost.badgers-in-foil.co.uk> <37E63690-617B-11D9-8556-000A95A67B22@v-i-a.net> <20050111003948.GA23491@vhost.badgers-in-foil.co.uk> <20050113084825.GA7817@vhost.badgers-in-foil.co.uk> Message-ID: <20050113094859.GA8982@vhost.badgers-in-foil.co.uk> On Thu, Jan 13, 2005 at 08:48:25AM +0000, David Holroyd wrote: > The syntax looks something like this: > > /** > * ...event docs... > */ > [Event("foo")] Oh -- I should point out that as2api doesn't support this yet, though. dave -- http://david.holroyd.me.uk/ From erixtekila at ifrance.com Thu Jan 13 15:41:47 2005 From: erixtekila at ifrance.com (erixtekila) Date: Thu, 13 Jan 2005 16:41:47 +0100 Subject: [as2api-dev] Nomenclatures for doc generation : Relative path issue In-Reply-To: <20050113084825.GA7817@vhost.badgers-in-foil.co.uk> References: <20050102225435.GA19232@vhost.badgers-in-foil.co.uk> <20050107111417.GA13436@vhost.badgers-in-foil.co.uk> <3AC90BE8-60CF-11D9-B3B9-000A95A67B22@ifrance.com> <20050107175156.GA18743@vhost.badgers-in-foil.co.uk> <20050108120222.GC4316@vhost.badgers-in-foil.co.uk> <37E63690-617B-11D9-8556-000A95A67B22@v-i-a.net> <20050111003948.GA23491@vhost.badgers-in-foil.co.uk> <20050113084825.GA7817@vhost.badgers-in-foil.co.uk> Message-ID: Hi, > I know that classes such as mx.containers.ScrollPane have > class-attributes relating to events. I've no idea exactly what these > do, but I suspect that annotating these attributes with documentation > would be the best way to do what want. > The syntax looks something like this: > > /** > * ...event docs... > */ > [Event("foo")] This is not for the same purpose. You could read a notice by peter joel who spot this feature : http://www.peterjoel.com/blog/index.php?=20 archive=3D2003_09_01_archive.xml#106277446938291338 What I was akin', is if it was hard and not really usefull to had =20 another tag to the javadoc comments who could be @event and generate =20 documentation nearly like @param. The purpose is to implement the mechanism of =20 eventDis=E2tcher in the documentation since it is very obscure (black =20= box). In fact, you have to : broadcast("eventName", params); So this process is absent from docs, but really usefull fro developpers. So i was thinking that there should be a way to document it clearly =20 with javadoc comments or perhaps should we add @event. I'm asking=85 One more question. Is it difficult for you to implement a way to put as much
in the =20= documentation as new * line discovered ? That way : /** * Description of the classe. * Little exemple */ will be formatted clearly in the documentation. Thanks for your work. Regards. From erixtekila at dotgeek.org Tue Jan 18 13:48:00 2005 From: erixtekila at dotgeek.org (dotgeek_erixtekila) Date: Tue, 18 Jan 2005 14:48:00 +0100 Subject: [as2api-dev] Newline support Message-ID: <917FD002-6957-11D9-9DBF-000A95A67B22@dotgeek.org> Hi, It'll be hard for as2api to support newline in comments to
in html output ? This could make docs more readable. Regards. From dave at badgers-in-foil.co.uk Tue Jan 18 15:30:05 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Tue, 18 Jan 2005 15:30:05 +0000 Subject: [as2api-dev] Newline support In-Reply-To: <917FD002-6957-11D9-9DBF-000A95A67B22@dotgeek.org> References: <917FD002-6957-11D9-9DBF-000A95A67B22@dotgeek.org> Message-ID: <20050118153003.GA11704@vhost.badgers-in-foil.co.uk> Hi, sorry for the slow reply to your last message, On Tue, Jan 18, 2005 at 02:48:00PM +0100, dotgeek_erixtekila wrote: > It'll be hard for as2api to support newline in comments to
in html > output ? > This could make docs more readable. More precise formatting control is dependant on implementing parsing of HTML markup within doc comments. I've always thought that HTML sucked as the choice of markup in JavaDoc, given that the Java metadata (@param et al) is identified using a totally different, almost incompatable, markup. Well, that's the way the world is now, so at some point I hope that as2api will learn how to understand HTML. dave -- http://david.holroyd.me.uk/ From dave at badgers-in-foil.co.uk Thu Jan 20 13:05:10 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Thu, 20 Jan 2005 13:05:10 +0000 Subject: [as2api-dev] Inheritance diagrams Message-ID: <20050120130510.GA21825@vhost.badgers-in-foil.co.uk> A small update: I did a bit of hacking the other day with as2api and the excelent Graphviz[1] tools. As a result, I've got as2api automatically generating class and interface inheritance diagrams for each package. Here's the result of this, run over the MM-provided .as files: http://www.badgers-in-foil.co.uk/projects/as2api/examples/flash_mx_2004/frameset.html [Quite a lot of the diagrams are dull, because not much inheritance goes on. mx.accessibility and mx.transitions have slightly more interesting results.] However, I've *only* been testing this under Linux, so far. I know that there are versions of graphviz for both Win and OSX, but I've yet to figure out how best to integrate the 'dot' tool on those platforms. dave [1] http://www.graphviz.org/ -- http://david.holroyd.me.uk/ From erixtekila at dotgeek.org Thu Jan 20 16:26:58 2005 From: erixtekila at dotgeek.org (erixtekila) Date: Thu, 20 Jan 2005 17:26:58 +0100 Subject: [as2api-dev] Inheritance diagrams In-Reply-To: <20050120130510.GA21825@vhost.badgers-in-foil.co.uk> References: <20050120130510.GA21825@vhost.badgers-in-foil.co.uk> Message-ID: <1B384CE2-6B00-11D9-9CE5-000A95A67B22@dotgeek.org> Hi, > However, I've *only* been testing this under Linux, so far. I know=20 > that > there are versions of graphviz for both Win and OSX, but I've yet to > figure out how best to integrate the 'dot' tool on those platforms. If you wish I could test it on OSX. I saw that the dot commandline tool is installable for the platform=85 But could you first do a compressed file of the files ? Or direct svn url to the changed files ? And is it possible to get a little explaiantion of how you configure=20 the ruby app to call dot tool ? Regards. > From dave at badgers-in-foil.co.uk Thu Jan 20 18:06:20 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Thu, 20 Jan 2005 18:06:20 +0000 Subject: [as2api-dev] Inheritance diagrams In-Reply-To: <1B384CE2-6B00-11D9-9CE5-000A95A67B22@dotgeek.org> References: <20050120130510.GA21825@vhost.badgers-in-foil.co.uk> <1B384CE2-6B00-11D9-9CE5-000A95A67B22@dotgeek.org> Message-ID: <20050120180619.GA26276@vhost.badgers-in-foil.co.uk> On Thu, Jan 20, 2005 at 05:26:58PM +0100, erixtekila wrote: > Hi, > > >However, I've *only* been testing this under Linux, so far. I know > >that > >there are versions of graphviz for both Win and OSX, but I've yet to > >figure out how best to integrate the 'dot' tool on those platforms. > If you wish I could test it on OSX. > I saw that the dot commandline tool is installable for the platform? > > But could you first do a compressed file of the files ? > Or direct svn url to the changed files ? > > And is it possible to get a little explaiantion of how you configure > the ruby app to call dot tool ? I haven't committed the changes yet; I will try to sort something out tonight, when I get home. There is currently no configuration at all: as2api just invokes the program "dot", and if is missing, will fail with an error (so can see why I didn't commit the code yet). dave -- http://david.holroyd.me.uk/ From dave at badgers-in-foil.co.uk Thu Jan 20 20:42:33 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Thu, 20 Jan 2005 20:42:33 +0000 Subject: [as2api-dev] Inheritance diagrams In-Reply-To: <1B384CE2-6B00-11D9-9CE5-000A95A67B22@dotgeek.org> References: <20050120130510.GA21825@vhost.badgers-in-foil.co.uk> <1B384CE2-6B00-11D9-9CE5-000A95A67B22@dotgeek.org> Message-ID: <20050120204232.GC27811@vhost.badgers-in-foil.co.uk> --2B/JsCI69OhZNC5r Content-Type: text/plain; charset=us-ascii Content-Disposition: inline On Thu, Jan 20, 2005 at 05:26:58PM +0100, erixtekila wrote: > >However, I've *only* been testing this under Linux, so far. I know > >that > >there are versions of graphviz for both Win and OSX, but I've yet to > >figure out how best to integrate the 'dot' tool on those platforms. > If you wish I could test it on OSX. > I saw that the dot commandline tool is installable for the platform? > > But could you first do a compressed file of the files ? Attached is my copy of html_output.rb. It contains a new package_diagrams() function (full of duplicated code still) that uses Ruby's system() function to invoke "dot". The two calls with the -Tpng option create the images for class/interface and the two calls with the -Tcmapx option generate a fragment of HTML for the image map. I imagine that if installing Graphviz results in all the tools appearing in your $PATH, that this will 'just work'. As I indicated in my last email, this isn't in a finished state yet, as as2api should really continue to function if the Graphviz tools are missing. Give it a go (and sorry if there are other problems with it -- this files also contains new code to generate an alphabetical index of AS types and methods). dave -- http://david.holroyd.me.uk/ --2B/JsCI69OhZNC5r Content-Type: text/plain; charset=us-ascii Content-Disposition: attachment; filename="html_output.rb" require 'xmlwriter' require 'doc_comment' require 'rexml/document' def link_type_proxy(out, type_proxy, qualified=false) if type_proxy.resolved? && type_proxy.resolved_type.document? link_type(out, type_proxy.resolved_type, qualified) else if type_proxy.resolved? if type_proxy.resolved_type.instance_of?(ASInterface) out.simple_element("span", type_proxy.local_name, {"class"=>"interface_name"}) else out.simple_element("span", type_proxy.local_name, {"class"=>"class_name"}) end else out.simple_element("span", type_proxy.local_name, {"class"=>"unresolved_type_name"}) end end end def link_for_type(type) base_path(type.qualified_name.gsub(/\./, "/")+".html") end def link_type(out, type, qualified=false) href = link_for_type(type) if type.instance_of?(ASInterface) attr_class = "interface_name" attr_title = "Interface #{type.qualified_name}" else attr_class = "class_name" attr_title = "Class #{type.qualified_name}" end if qualified out.simple_element("a", type.qualified_name, {"href"=>href, "class"=>attr_class, "title"=>attr_title}) else out.simple_element("a", type.unqualified_name, {"href"=>href, "class"=>attr_class, "title"=>attr_title}) end end def method_synopsis(out, method) out.element("code", {"class", "method_synopsis"}) do if method.access.is_static out.pcdata("static ") end unless method.access.visibility.nil? out.pcdata("#{method.access.visibility.body} ") end out.pcdata("function ") out.element("strong", {"class"=>"method_name"}) do out.pcdata(method.name) end out.pcdata("(") method.arguments.each_with_index do |arg, index| out.pcdata(", ") if index > 0 out.pcdata(arg.name) if arg.arg_type out.pcdata(":") link_type_proxy(out, arg.arg_type) end end out.pcdata(")") if method.return_type out.pcdata(":") link_type_proxy(out, method.return_type) end end end def field_synopsis(out, field) out.element("code", {"class", "field_synopsis"}) do if field.instance_of?(ASImplicitField) implicit_field_synopsis(out, field) else explicit_field_synopsis(out, field) end end end def explicit_field_synopsis(out, field) if field.access.is_static out.pcdata("static ") end unless field.access.visibility.nil? out.pcdata("#{field.access.visibility.body} ") end out.element("strong", {"class"=>"field_name"}) do out.pcdata(field.name) end if field.field_type out.pcdata(":") link_type_proxy(out, field.field_type) end end def implicit_field_synopsis(out, field) if field.access.is_static out.pcdata("static ") end unless field.access.visibility.nil? out.pcdata("#{field.access.visibility.body} ") end out.element("strong", {"class"=>"field_name"}) do out.pcdata(field.name) end field_type = field.field_type unless field_type.nil? out.pcdata(":") link_type_proxy(out, field_type) end unless field.readwrite? out.pcdata(" ") out.element("em", {"class"=>"read_write_only"}) do if field.read? out.pcdata("[Read Only]") else out.pcdata("[Write Only]") end end end end def class_navigation(out) out.element("div", {"class", "main_nav"}) do out.simple_element("a", "Overview", {"href"=>base_path("overview-summary.html")}) out.simple_element("a", "Package", {"href"=>"package-summary.html"}) out.simple_element("span", "Class", {"class"=>"nav_current"}) out.simple_element("a", "Index", {"href"=>base_path("index-files/index.html")}) end end def document_method(out, type, method, alt_row=false) css_class = "method_details" css_class << " alt_row" if alt_row out.element("div", {"class"=>css_class}) do out.empty_tag("a", {"name"=>"method_#{method.name}"}) out.simple_element("h3", method.name) method_synopsis(out, method) if method.comment out.element("blockquote") do docs = DocComment.new(type.type_resolver) docs.parse(method.comment.body) out.pcdata(docs.description) out.element("dl", {"class"=>"method_additional_info"}) do # TODO: assumes that params named in docs match formal arguments # should really filter out those that don't match before this # test if docs.parameters? out.simple_element("dt", "Parameters") out.element("dd") do out.element("table", {"class"=>"arguments", "summary"=>""}) do method.arguments.each do |arg| desc = docs.param(arg.name) if desc out.element("tr") do out.element("td") do out.simple_element("code", arg.name) end out.simple_element("td", desc) end end end end end end unless docs.desc_return.nil? out.simple_element("dt", "Return") out.element("dd") do out.pcdata(docs.desc_return) end end if docs.exceptions? out.simple_element("dt", "throws") out.element("dd") do out.element("table", {"class"=>"exceptions", "summary"=>""}) do docs.each_exception do |type, desc| out.element("tr") do out.element("td") do link_type_proxy(out, type) end out.simple_element("td", desc) end end end end end if docs.seealso? out.simple_element("dt", "See Also") out.element("dd") do list_see_also(out, docs) end end end end end end end def document_field(out, type, field) out.empty_tag("a", {"name"=>"field_#{field.name}"}) out.simple_element("h3", field.name) out.element("div", {"class"=>"field_details"}) do field_synopsis(out, field) if field.comment out.element("blockquote") do docs = DocComment.new(type.type_resolver) docs.parse(field.comment.body) out.pcdata(docs.description) out.element("dl", {"class"=>"field_additional_info"}) do if docs.seealso? out.simple_element("dt", "See Also") out.element("dd") do list_see_also(out, docs) end end end end end end end $base_path = "" $path = "" def base_path(file) "#{$base_path}#{file}" end def in_subdir(path) save_path = $path save_base_path = $base_path.dup path = path.split(File::SEPARATOR) if path.first == "" path.shift $path = "/" end path.each do |part| if $path == "" $path = part else $base_path << ".."+File::SEPARATOR $path = File.join($path, part) end unless FileTest.exist?($path) Dir.mkdir($path) end end yield $path = save_path $base_path = save_base_path end def write_file(name) File.open(File.join($path, name), "w") do |io| yield io end end def html_file(name, title, encoding=nil) write_file("#{name}.html") do |io| out = XMLWriter.new(io) encoding = "iso-8859-1" if encoding.nil? out.pi("xml version=\"1.0\" encoding=\"#{encoding}\"") out.element("html") do out.element("head") do out.simple_element("title", title) out.empty_tag("link", {"rel"=>"stylesheet", "type"=>"text/css", "href"=>base_path("style.css")}) out.empty_tag("meta", {"name"=>"generator", "content"=>"http://www.badgers-in-foil.co.uk/projects/as2api/"}) yield out end end end end def html_body(name, title, encoding=nil) html_file(name, title, encoding) do |out| out.element("body") do yield out footer(out) end end end def footer(out) out.element("div", {"class"=>"footer"}) do out.simple_element("a", "as2api", {"href"=>"http://www.badgers-in-foil.co.uk/projects/as2api/", "title"=>"ActionScript 2 API Documentation Generator"}) end end def type_hierachy(out, type) # TODO: ASCII art is an accessability problem. Replace with images that have # alt-text, or use CSS to generate content, e.g. # out.element("pre", {"class"=>"type_hierachy"}) do count = 0 unless type.extends.nil? count = type_hierachy_recursive(out, type.extends) end if count > 0 out.pcdata(" " * count) out.pcdata("+--") end out.simple_element("strong", type.qualified_name) end end def type_hierachy_recursive(out, type_proxy) count = 0 if type_proxy.resolved? type = type_proxy.resolved_type unless type.extends.nil? count = type_hierachy_recursive(out, type.extends) end else out.pcdata("????\n") count = 1 end if count > 0 out.pcdata(" " * count) out.pcdata("+--") end link_type_proxy(out, type_proxy, true) out.pcdata("\n") return count + 1 end def field_index_list(out, type) out.element("div", {"class"=>"field_index"}) do out.simple_element("h2", "Field Index") list_fields(out, type) out.element("dl") do type.each_ancestor do |type| if type.fields? out.element("dt") do out.pcdata("Inherited from ") link_type(out, type) end out.element("dd") do list_fields(out, type, link_for_type(type)) end end end end end end def list_fields(out, type, href_prefix="") fields = type.fields.sort fields.each_with_index do |field, index| out.pcdata(", ") if index > 0 out.element("code") do out.element("a", {"href"=>"#{href_prefix}#field_#{field.name}"}) do out.pcdata(field.name) end end end end def field_detail_list(out, type) out.element("div", {"class"=>"field_detail_list"}) do out.simple_element("h2", "Field Detail") type.each_field do |field| document_field(out, type, field) end end end def method_index_list(out, type) out.element("div", {"class"=>"method_index"}) do out.simple_element("h2", "Method Index") if type.constructor? out.element("p") do out.element("code") do out.pcdata("new ") out.element("a", {"href"=>"#method_#{type.constructor.name}"}) do out.pcdata(type.constructor.name+"()") end end end end known_method_names = [] list_methods(out, type, known_method_names) out.element("dl") do type.each_ancestor do |type| if type.methods? out.element("dt") do out.pcdata("Inherited from ") link_type(out, type) end out.element("dd") do list_methods(out, type, known_method_names, link_for_type(type)) end end end end end end def list_methods(out, type, known_method_names, href_prefix="") methods = type.methods.select do |method| !known_method_names.include?(method.name) end methods.sort! methods.each_with_index do |method, index| known_method_names << method.name out.pcdata(", ") if index > 0 out.element("a", {"href"=>"#{href_prefix}#method_#{method.name}"}) do out.pcdata(method.name+"()") end end end def method_detail_list(out, type) out.element("div", {"class"=>"method_detail_list"}) do out.simple_element("h2", "Method Detail") count = 0 type.each_method do |method| document_method(out, type, method, count%2==0) count += 1 end end end def constructor_detail(out, type) out.element("div", {"class"=>"constructor_detail_list"}) do out.simple_element("h2", "Constructor Detail") document_method(out, type, type.constructor) end end def document_type(type) encoding = if type.source_utf8 "utf-8" else "iso-8859-1" end html_body(type.unqualified_name, type.qualified_name, encoding) do |out| out.simple_element("a", "", {"href"=>"#skip_nav", "title"=>"Skip navigation"}) # accessability class_navigation(out) out.simple_element("a", "", {"name"=>"skip_nav"}) if type.instance_of?(ASClass) out.simple_element("h1", "Class "+type.qualified_name) elsif type.instance_of?(ASInterface) out.simple_element("h1", "Interface "+type.qualified_name) end type_hierachy(out, type) if type.implements_interfaces? out.element("div", {"class"=>"interfaces"}) do out.simple_element("h2", "Implemented Interfaces") type.each_interface do |interface| # TODO: need to resolve interface name, make links out.element("code") do link_type_proxy(out, interface) end out.pcdata(" ") end end end out.element("div", {"class"=>"type_description"}) do if type.comment docs = DocComment.new(type.type_resolver) docs.parse(type.comment.body) out.simple_element("h2", "Description") out.element("p") do out.pcdata(docs.description) end out.element("dl", {"class"=>"type_details"}) do if docs.seealso? out.simple_element("dt", "See Also") out.element("dd") do list_see_also(out, docs) end end end end end field_index_list(out, type) if type.fields? method_index_list(out, type) if type.methods? constructor_detail(out, type) if type.constructor? field_detail_list(out, type) if type.fields? method_detail_list(out, type) if type.methods? class_navigation(out) end end def list_see_also(out, docs) docs.each_see_also do |see| out.comment(" parsing for see-also not done yet ") out.simple_element("p", see) end end def package_dir_for(package) package.name.gsub(/\./, "/") end def package_display_name_for(package) return "(Default)" if package.name == "" package.name end def package_link_for(package, page) return page if package.name == "" package_dir_for(package) + "/" + page end def package_navigation(out) out.element("div", {"class", "main_nav"}) do out.simple_element("a", "Overview", {"href"=>base_path("overview-summary.html")}) out.simple_element("span", "Package", {"class"=>"nav_current"}) out.simple_element("span", "Class") out.simple_element("a", "Index", {"href"=>base_path("index-files/index.html")}) end end def package_pages(package) in_subdir(package_dir_for(package)) do package_diagrams(package) package_index(package) package_frame(package) end end def package_index(package) html_body("package-summary", "Package #{package_display_name_for(package)} API Documentation") do |out| out.simple_element("a", "", {"href"=>"#skip_nav", "title"=>"Skip navigation"}) # accessability package_navigation(out) out.simple_element("a", "", {"name"=>"skip_nav"}) out.simple_element("h1", "Package "+package_display_name_for(package)) interfaces = package.interfaces unless interfaces.empty? interfaces.sort! out.element("table", {"class"=>"summary_list", "summary"=>""}) do out.element("tr") do out.simple_element("th", "Interface Summary", {"colspan"=>"2"}) end interfaces.each do |type| out.element("tr") do out.element("td") do out.simple_element("a", type.unqualified_name, {"href"=>type.unqualified_name+".html"}) end out.element("td") do # TODO: package description end end end end end classes = package.classes unless classes.empty? classes.sort! out.element("table", {"class"=>"summary_list", "summary"=>""}) do out.element("tr") do out.simple_element("th", "Class Summary", {"colspan"=>"2"}) end classes.each do |type| out.element("tr") do out.element("td") do out.simple_element("a", type.unqualified_name, {"href"=>type.unqualified_name+".html"}) end out.element("td") do # TODO: package description end end end end end if FileTest.exists?(File.join($path, "package-classes.png")) out.simple_element("h1", "Class Inheritance Diagram") out.element("div", {"class"=>"diagram"}) do if FileTest.exists?(File.join($path, "package-classes.cmapx")) map = true File.open(File.join($path, "package-classes.cmapx")) do |io| copy_xml(io, out) end else map = false end attr = {"src"=>"package-classes.png"} if map attr["usemap"] = "class_diagram" end out.empty_tag("img", attr) end end if FileTest.exists?(File.join($path, "package-interfaces.png")) out.simple_element("h1", "Interface Inheritance Diagram") out.element("div", {"class"=>"diagram"}) do if FileTest.exists?(File.join($path, "package-interfaces.cmapx")) map = true File.open(File.join($path, "package-interfaces.cmapx")) do |io| copy_xml(io, out) end else map = false end attr = {"src"=>"package-interfaces.png"} if map attr["usemap"] = "interface_diagram" end out.empty_tag("img", attr) end end package_navigation(out) end end def package_frame(package) html_file("package-frame", "Package #{package_display_name_for(package)} API Naviation") do |out| out.element("body") do # TODO: don't use out.element("strong") do out.simple_element("a", package_display_name_for(package), {"href"=>"package-summary.html", "target"=>"type_frame"}) end interfaces = package.interfaces unless interfaces.empty? interfaces.sort! out.element("table", {"class"=>"navigation_list"}) do out.element("tr") do out.simple_element("th", "Interfaces") end interfaces.each do |type| out.element("tr") do out.element("td") do out.simple_element("a", type.unqualified_name, {"href"=>type.unqualified_name+".html", "target"=>"type_frame", "title"=>type.qualified_name}) end end end end end classes = package.classes unless classes.empty? classes.sort! out.element("table", {"class"=>"navigation_list"}) do out.element("tr") do out.simple_element("th", "Classes") end classes.each do |type| out.element("tr") do out.element("td") do out.simple_element("a", type.unqualified_name, {"href"=>type.unqualified_name+".html", "target"=>"type_frame", "title"=>type.qualified_name}) end end end end end end end end def package_diagrams(package) asclasses = package.classes unless asclasses.empty? write_file("classes.dot") do |io| io.puts("strict digraph class_diagram {") io.puts(" rankdir=LR;") asclasses.each do |astype| io.puts(" #{astype.unqualified_name}[") io.puts(" label=\"#{astype.unqualified_name}\",") io.puts(" URL=\"#{astype.unqualified_name}.html\",") io.puts(" tooltip=\"#{astype.qualified_name}\",") io.puts(" fontname=\"Times-Italic\",") if astype.is_a?(ASInterface) io.puts(" shape=\"record\"") io.puts(" ];") end asclasses.each do |astype| parent = astype.extends if !parent.nil? && parent.resolved? if parent.resolved_type.package_name == package.name io.puts(" #{parent.resolved_type.unqualified_name} -> #{astype.unqualified_name};") end end end io.puts("}") end system("dot", "-Tpng", "-o", File.join($path, "package-classes.png"), File.join($path, "classes.dot")) system("dot", "-Tcmapx", "-o", File.join($path, "package-classes.cmapx"), File.join($path, "classes.dot")) #File.delete(File.join($path, "types.dot")) end asinterfaces = package.interfaces unless asinterfaces.empty? write_file("interfaces.dot") do |io| io.puts("strict digraph interface_diagram {") io.puts(" rankdir=LR;") asinterfaces.each do |astype| io.puts(" #{astype.unqualified_name}[") io.puts(" label=\"#{astype.unqualified_name}\",") io.puts(" URL=\"#{astype.unqualified_name}.html\",") io.puts(" tooltip=\"#{astype.qualified_name}\",") io.puts(" fontname=\"Times-Italic\",") if astype.is_a?(ASInterface) io.puts(" shape=\"record\"") io.puts(" ];") end asinterfaces.each do |astype| parent = astype.extends if !parent.nil? && parent.resolved? if parent.resolved_type.package_name == package.name io.puts(" #{parent.resolved_type.unqualified_name} -> #{astype.unqualified_name};") end end end io.puts("}") end system("dot", "-Tpng", "-o", File.join($path, "package-interfaces.png"), File.join($path, "interfaces.dot")) system("dot", "-Tcmapx", "-o", File.join($path, "package-interfaces.cmapx"), File.join($path, "interfaces.dot")) #File.delete(File.join($path, "types.dot")) end end class XMLAdapter def initialize(out) @out = out end def tag_start(name, attrs) attr_map = {} attrs.each do |el| attr_map[el[0]] = el[1] end @out.start_tag(name, attr_map) end def tag_end(name) @out.end_tag(name) end def text(text) @out.pcdata(text) end end def copy_xml(io, out) listener = XMLAdapter.new(out) REXML::Document.parse_stream(io, listener) end def overview_navigation(out) out.element("div", {"class", "main_nav"}) do out.simple_element("span", "Overview", {"class"=>"nav_current"}) out.simple_element("span", "Package") out.simple_element("span", "Class") out.simple_element("a", "Index", {"href"=>"index-files/index.html"}) end end def overview(type_agregator) html_body("overview-summary", "API Overview") do |out| out.simple_element("a", "", {"href"=>"#skip_nav", "title"=>"Skip navigation"}) # accessability overview_navigation(out) out.simple_element("a", "", {"name"=>"skip_nav"}) out.simple_element("h1", "API Overview") out.element("table", {"class"=>"summary_list", "summary"=>""}) do out.element("tr") do out.simple_element("th", "Packages", {"colspan"=>"2"}) end packages = type_agregator.packages.sort packages.each do |package| out.element("tr") do out.element("td") do name = package_display_name_for(package) out.simple_element("a", name, {"href"=>package_link_for(package, "package-summary.html")}) end out.element("td") do # TODO: package description end end end end overview_navigation(out) end end def overview_frame(type_agregator) html_file("overview-frame", "API Overview") do |out| out.element("body") do out.element("table", {"class"=>"navigation_list"}) do out.element("tr") do out.simple_element("th", "Packages") end out.element("tr") do out.element("td") do out.simple_element("a", "(All Types)", {"href"=>"all-types-frame.html", "target"=>"current_package_frame"}) end end packages = type_agregator.packages.sort packages.each do |package| out.element("tr") do out.element("td") do name = package_display_name_for(package) out.simple_element("a", name, {"href"=>package_link_for(package, "package-frame.html"), "target"=>"current_package_frame", "title"=>name}) end end end end end end end def package_list(type_agregator) # REVISIT: Will a package list actually be useful for ActionScript, or can # we always assume that any code that makes reference to a type # must have access to that type's source in order to compile? # (In theory, this file will allow javadoc to link to ActionScript # classes, so maybe keep it just for that.) write_file("package-list") do |out| type_agregator.each_package do |package| out.puts(package.name) unless package.name == "" end end end def all_types_frame(type_agregator) html_file("all-types-frame", "as2api") do |out| out.element("body") do out.element("table", {"class"=>"navigation_list"}) do out.element("tr") do out.simple_element("th", "All Types") end types = type_agregator.types.sort do |a,b| cmp = a.unqualified_name.downcase <=> b.unqualified_name.downcase if cmp == 0 a.qualified_name <=> b.qualified_name else cmp end end types.each do |type| if type.document? href = type.qualified_name.gsub(/\./, "/") + ".html" out.element("tr") do out.element("td") do out.simple_element("a", type.unqualified_name, {"href"=>href, "title"=>type.qualified_name, "target"=>"type_frame"}) end end end end end end end end def frameset html_file("frameset", "as2api") do |out| out.element("frameset", {"cols"=>"20%,80%"}) do out.element("frameset", {"rows"=>"30%,70%"}) do out.empty_tag("frame", {"src"=>"overview-frame.html", "name"=>"all_packages_frame", "title"=>"All Packages"}) out.empty_tag("frame", {"src"=>"all-types-frame.html", "name"=>"current_package_frame", "title"=>"All types"}) end out.empty_tag("frame", {"src"=>"overview-summary.html", "name"=>"type_frame", "title"=>"Package and type descriptions"}) end out.element("noframes") do out.simple_element("a", "Non-frameset overview page", {"href"=>"overview-summary.html"}) end end end class IndexTerm def <=>(other) cmp = term.downcase <=> other.term.downcase cmp = term <=> other.term if cmp == 0 cmp end end class TypeIndexTerm < IndexTerm def initialize(astype) @astype = astype end def term @astype.unqualified_name end def link(out) link_type(out, @astype) out.pcdata(" in package ") out.pcdata(@astype.package_name) end end class MemberIndexTerm < IndexTerm def initialize(astype, asmember) @astype = astype @asmember = asmember end def term @asmember.name end end class MethodIndexTerm < MemberIndexTerm def link(out) href_prefix = link_for_type(@astype) out.element("a", {"href"=>"#{href_prefix}#method_#{@asmember.name}"}) do out.pcdata(@asmember.name + "()") end out.pcdata(" method in ") link_type(out, @astype, true) end end class FieldIndexTerm < MemberIndexTerm def link(out) href_prefix = link_for_type(@astype) out.element("a", {"href"=>"#{href_prefix}#field_#{@asmember.name}"}) do out.pcdata(@asmember.name) end out.pcdata(" field in ") link_type(out, @astype, true) end end def index_navigation(out) out.element("div", {"class", "main_nav"}) do out.simple_element("a", "Overview", {"href"=>base_path("overview-summary.html")}) out.simple_element("span", "Package") out.simple_element("span", "Class") out.simple_element("span", "Index", {"class"=>"nav_current"}) end end def index_files(type_agregator) index = [] # TODO: include packages type_agregator.each_type do |astype| if astype.document? index << TypeIndexTerm.new(astype) astype.each_method do |asmethod| index << MethodIndexTerm.new(astype, asmethod) end if astype.is_a?(ASClass) astype.each_field do |asfield| index << FieldIndexTerm.new(astype, asfield) end end end end index.sort! in_subdir("index-files") do html_file("index", "Alphabetical Index") do |out| index_navigation(out) index.each do |element| out.element("p") do element.link(out) end end index_navigation(out) end end end def document_types(output_path, type_agregator) in_subdir(output_path) do frameset() overview(type_agregator) overview_frame(type_agregator) package_list(type_agregator) all_types_frame(type_agregator) # packages.. type_agregator.each_package do |package| package_pages(package) end # types.. type_agregator.each_type do |type| if type.document? in_subdir(type.package_name.gsub(/\./, "/")) do document_type(type) end end end index_files(type_agregator) end end --2B/JsCI69OhZNC5r-- From viacontact at v-i-a.net Thu Jan 20 21:49:39 2005 From: viacontact at v-i-a.net (viaContact) Date: Thu, 20 Jan 2005 22:49:39 +0100 Subject: [as2api-dev] Inheritance diagrams In-Reply-To: <20050120204232.GC27811@vhost.badgers-in-foil.co.uk> References: <20050120130510.GA21825@vhost.badgers-in-foil.co.uk> <1B384CE2-6B00-11D9-9CE5-000A95A67B22@dotgeek.org> <20050120204232.GC27811@vhost.badgers-in-foil.co.uk> Message-ID: <2F531233-6B2D-11D9-805E-000A95A67B22@v-i-a.net> Here is the error i get : ./html_output.rb:4:in `require': No such file to load -- rexml/document=20= (LoadError) from ./html_output.rb:4 from documenter.rb:53:in `require' from documenter.rb:53 Seems that i miss one folder rexml. > this > files also contains new code to generate an alphabetical index of AS > types and methods). I saw on your output, and it's really a great feature. Waiting for the updated files=85 Thanks. NB : used dot commandline, and everything goes just fine=85 sweat.= From dave at badgers-in-foil.co.uk Thu Jan 20 23:31:38 2005 From: dave at badgers-in-foil.co.uk (David Holroyd) Date: Thu, 20 Jan 2005 23:31:38 +0000 Subject: [as2api-dev] Inheritance diagrams In-Reply-To: <2F531233-6B2D-11D9-805E-000A95A67B22@v-i-a.net> References: <20050120130510.GA21825@vhost.badgers-in-foil.co.uk> <1B384CE2-6B00-11D9-9CE5-000A95A67B22@dotgeek.org> <20050120204232.GC27811@vhost.badgers-in-foil.co.uk> <2F531233-6B2D-11D9-805E-000A95A67B22@v-i-a.net> Message-ID: <20050120233137.GE27811@vhost.badgers-in-foil.co.uk> On Thu, Jan 20, 2005 at 10:49:39PM +0100, viaContact wrote: > Here is the error i get : > ./html_output.rb:4:in `require': No such file to load -- rexml/document > (LoadError) > from ./html_output.rb:4 > from documenter.rb:53:in `require' > from documenter.rb:53 > > Seems that i miss one folder rexml. I've started making use of REXML, an XML parser for Ruby. I hear tell that REXML is included in the base installation since Ruby 1.8, but if you're using an older Ruby, you'll need a seperate download: http://www.germane-software.com/software/rexml/ dave -- http://david.holroyd.me.uk/