Re: [Flightgear-devel] properties documentation
Mike Bonar writes: I would be happy to take on this responsibility. It will give me a chance to get to know the code before I start messing with it ;-) So, feel free to bombard me with direction. What are the priorities? Are we going to stick with javadoc format? If so, know any good javadoc engines (having no success with doxymacs so far). Curt will have to provide any official answer, but I think that we should probably stick with DOxygen -- it uses JavaDoc format with a few extensions, and there are other engines that also understand JavaDoc format should the need arise. DOxymacs is just an Emacs mode to help writing formatted comments, isn't it? It shouldn't really be necessary -- they're not hard to write by hand. All the best, David -- David Megginson, [EMAIL PROTECTED], http://www.megginson.com/ ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel
Re: [Flightgear-devel] properties documentation
Mike Bonar writes: If I'm wasting my time just let me know. Not at all. Curt hasn't had time to update the doxygen docs for SimGear very frequently, or to generate and post any at all for FlightGear and TerraGear. I've already added a fair amount of JavaDoc-like comments to both, and if someone is willing to take reponsibility for generating and maintaining these, I will be very grateful. Thanks, and all the best, David -- David Megginson, [EMAIL PROTECTED], http://www.megginson.com/ ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel
Re: [Flightgear-devel] properties documentation
I am currently experimenting with doxemacs, a lisp extension to emacs that aids in formatting code for use with doxygen. Being an emacs newbie this might take a few days to get working ;-) I'll upload samples for everyone to see shortly. In the meantime, here are a couple of sites that have got doxygen working well. They show the kinds of things we can include if we want. Regards, Mike http://wbxmllib.sourceforge.net/html/index.html http://www.focus-sw.com/doc/FTMP_MBCC/ http://bakery.sourceforge.net/reference/html/index.html On Monday 23 December 2002 10:53, David Megginson wrote: Jon Berndt writes: Right. I was looking at it from another angle. That is, from the source code side. JSBSim uses properties and in the header we can probably document all the properties for a particular class. When Doxygen builds the docs from header comments, those will be included. Absolutely right; we just need a recommended way to document that. All the best, David -- David Megginson, [EMAIL PROTECTED], http://www.megginson.com/ ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel
Re: [Flightgear-devel] properties documentation
Correction: doxymacs. On Friday 27 December 2002 16:08, Mike Bonar wrote: I am currently experimenting with doxemacs, a lisp extension to emacs that aids in formatting code for use with doxygen. Being an emacs newbie this ...snip ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel
Re: [Flightgear-devel] properties documentation
On Fri, 27 Dec 2002 16:08:30 -0600 Mike Bonar [EMAIL PROTECTED] wrote: I am currently experimenting with doxemacs, a lisp extension to emacs that aids in formatting code for use with doxygen. Being an emacs newbie this might take a few days to get working ;-) I'll upload samples for everyone to see shortly. In the meantime, here are a couple of sites that have got doxygen working well. They show the kinds of things we can include if we want. Regards, Mike http://wbxmllib.sourceforge.net/html/index.html http://www.focus-sw.com/doc/FTMP_MBCC/ http://bakery.sourceforge.net/reference/html/index.html http://www.simgear.org/doxygen/index.html Bernie ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel
Re: [Flightgear-devel] properties documentation
If I'm wasting my time just let me know. On Friday 27 December 2002 17:01, Bernie Bright wrote: On Fri, 27 Dec 2002 16:08:30 -0600 Mike Bonar [EMAIL PROTECTED] wrote: ...snip doxygen working well. They show the kinds of things we can include if we ...snip http://www.simgear.org/doxygen/index.html Bernie ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel
RE: [Flightgear-devel] properties documentation
This may sound like a lame idea. I am not all that versed on xml technology, but it seems to me that there is a standard form for something like this. In the database world there is something called a Data dictionary that works as a central repository for data items, their types, default values, short descriptions, long descriptions, etc. I've seen Doxygen mentioned here previously, IIRC. I can vouch for its effectiveness as a documentation aid. Doxygen can produce a pretty detailed index. This would be a start, if nothing else. I also wonder if there shouldn't be a way to - dump at run time - the listing you ask for (for instance in a debug compile, one could have this capability). Jon smime.p7s Description: application/pkcs7-signature
RE: [Flightgear-devel] properties documentation
Jon Berndt [EMAIL PROTECTED] said: This may sound like a lame idea. I am not all that versed on xml technology, but it seems to me that there is a standard form for something like this. In the database world there is something called a Data dictionary that works as a central repository for data items, their types, default values, short descriptions, long descriptions, etc. I've seen Doxygen mentioned here previously, IIRC. I can vouch for its effectiveness as a documentation aid. Doxygen can produce a pretty detailed index. This would be a start, if nothing else. I also wonder if there shouldn't be a way to - dump at run time - the listing you ask for (for instance in a debug compile, one could have this capability). Yes and I think Doxygen sounds like a good thing. To be honest I don't really have much trouble figuring out what the properties are and if I need to know what sets/reads them, grep works fine. But it does seem as though a central dictionary (for lack of a better term) to which xml configs refer might yield some benifit for new programmers as well as simplifying the coding of xml files. Maybe even error checking. Again this is a topic I'm not familiar with...just asking the question. Best, Jim ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel
re: [Flightgear-devel] properties documentation
Jim Wilson writes: Is this the sort of thing that a standard DTD document provides? Or could we develop our own dictionary of sorts? I'm suggesting that this could provide the documentation we need (if it is centralized). No, DTDs are strictly structural -- think of it as a specialized version of BNF. If it assumed an active role in the property system, then it could be used as a resource to simplify coding individual xml files, since default values, types, and other properties could be sourced from the central dictionary. We can create a dictionary in XML, but then we have the problem of maintaining properties in multiple locations. Another alternative is to allow documentation attributes for all properties: controls doc=aircraft control inputs aileron doc=aileron position: left=-1, neutral=0,right=10/aileron /controls and so on. That's the inelegant, English-only solution; the more elegant solution is to document in external files, but then we get maintenance issues again. All the best, David -- David Megginson, [EMAIL PROTECTED], http://www.megginson.com/ ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel
Re: [Flightgear-devel] properties documentation
Doxygen would need to be tweaked a bit, since it is not set up for XML I started hunting for an XML documentation engine last night. All the ones I have found so far do only one page at a time. We want it to do the same thing that Doxygen does, which is to read through all the subdirectories, dump the XML into html files and build an index.html I'll put the Doxygen output from the C code up on my site as soon as I clean it up. It read the entire SimGear into a single 5MB html file ;-) Mike On Monday 23 December 2002 08:17, Jim Wilson wrote: Jon Berndt [EMAIL PROTECTED] said: This may sound like a lame idea. I am not all that versed on xml technology, but it seems to me that there is a standard form for something like this. In the database world there is something called a Data dictionary that works as a central repository for data items, their types, default values, short descriptions, long descriptions, etc. I've seen Doxygen mentioned here previously, IIRC. I can vouch for its effectiveness as a documentation aid. Doxygen can produce a pretty detailed index. This would be a start, if nothing else. I also wonder if there shouldn't be a way to - dump at run time - the listing you ask for (for instance in a debug compile, one could have this capability). Yes and I think Doxygen sounds like a good thing. To be honest I don't really have much trouble figuring out what the properties are and if I need to know what sets/reads them, grep works fine. But it does seem as though a central dictionary (for lack of a better term) to which xml configs refer might yield some benifit for new programmers as well as simplifying the coding of xml files. Maybe even error checking. Again this is a topic I'm not familiar with...just asking the question. Best, Jim ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel
RE: [Flightgear-devel] properties documentation
Doxygen would need to be tweaked a bit, since it is not set up for XML I Right. I was looking at it from another angle. That is, from the source code side. JSBSim uses properties and in the header we can probably document all the properties for a particular class. When Doxygen builds the docs from header comments, those will be included. Jon smime.p7s Description: application/pkcs7-signature
RE: [Flightgear-devel] properties documentation
Jon Berndt writes: Right. I was looking at it from another angle. That is, from the source code side. JSBSim uses properties and in the header we can probably document all the properties for a particular class. When Doxygen builds the docs from header comments, those will be included. Absolutely right; we just need a recommended way to document that. All the best, David -- David Megginson, [EMAIL PROTECTED], http://www.megginson.com/ ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel
[Flightgear-devel] properties documentation
This may sound like a lame idea. I am not all that versed on xml technology, but it seems to me that there is a standard form for something like this. In the database world there is something called a Data dictionary that works as a central repository for data items, their types, default values, short descriptions, long descriptions, etc. Is this the sort of thing that a standard DTD document provides? Or could we develop our own dictionary of sorts? I'm suggesting that this could provide the documentation we need (if it is centralized). If it assumed an active role in the property system, then it could be used as a resource to simplify coding individual xml files, since default values, types, and other properties could be sourced from the central dictionary. Best, Jim ___ Flightgear-devel mailing list [EMAIL PROTECTED] http://mail.flightgear.org/mailman/listinfo/flightgear-devel
