[kepler-dev] Documentation and XML
Chad Berkley
berkley at nceas.ucsb.edu
Fri Feb 2 08:00:40 PST 2007
Hey Christopher,
Glad I didn't break anything. I was kinda worried about that with such
a huge change. The way I'm validating them right now is running the
'ant generateDoc' command from kepler, which builds all the java docs
and does an XSLT conversion to HTML. Unfortunately, this doesn't
actually check the validity of the XML though. The way I know if the
XML is valid is I try to upload all of the files to the kepler
repository (ant bootstrapRepository) which runs them all through xerces
in the process and throws errors if there's any invalid stuff in there.
Matt and I discussed this yesterday and I think I'm going to try to
write a script that will check the validity of the XML every time
someone tries to check a file into CVS. The script would reject the
check in if the XML is invalid. Hopefully I'll be able to get to that
soon, but right now I'm trying to get the repository working well for
the mini-conf, so maybe after the conference I'll get back to this.
chad
Christopher Brooks wrote:
> Hi Chad,
> Many thanks for cleaning up the Ptolemy sources!
> I see by your changes to the Ptolemy tree that you made
> lots of changes and it looks like none of them broke the build.
> (woo!woo!)
>
> How are you testing these changes, or in other words, how will
> we know when a file's comments are not fully legitimate
> xml?
>
> _Christopher
>
> 2007-02-01 12:21 berkley
>
> * ptolemy/: actor/TypedCompositeActor.java (1.94),
> actor/lib/AddSubtract.java (1.38),
> actor/lib/ArrayLevelCrossing.java (1.20),
> actor/lib/ArrayPeakSearch.java (1.32),
> actor/lib/ArrayToElements.java (1.24), actor/lib/Average.java
> (1.47), actor/lib/BooleanMultiplexor.java (1.27),
> actor/lib/BooleanSwitch.java (1.26),
> actor/lib/DiscreteRandomSource.java (1.52),
> actor/lib/ElementsToArray.java (1.25), actor/lib/Exec.java (1.62),
> actor/lib/Expression.java (1.128), actor/lib/Interpolator.java
> (1.45), actor/lib/LookupTable.java (1.34),
> actor/lib/MultiplyDivide.java (1.38), actor/lib/NonStrictTest.java
> (1.84), actor/lib/Quantizer.java (1.41), actor/lib/Recorder.java
> (1.45), actor/lib/Remainder.java (1.31), actor/lib/Rician.java
> (1.26), actor/lib/Select.java (1.27), actor/lib/SetVariable.java
> (1.39), actor/lib/Sleep.java (1.37), actor/lib/Stop.java (1.31),
> actor/lib/Switch.java (1.25), actor/lib/Test.java (1.73),
> actor/lib/ThrowModelError.java (1.27), actor/lib/TrigFunction.java
> (1.41), actor/lib/TypeTest.java (1.28),
> actor/lib/VectorAssembler.java (1.27),
> actor/lib/VectorDisassembler.java (1.31),
> actor/lib/conversions/BooleanToAnything.java (1.20),
> actor/lib/conversions/CartesianToPolar.java (1.27),
> actor/lib/conversions/ComplexToPolar.java (1.32),
> actor/lib/conversions/InUnitsOf.java (1.22),
> actor/lib/conversions/LongToDouble.java (1.25),
> actor/lib/conversions/StringToXML.java (1.24),
> actor/lib/gui/ArrayPlotter.java (1.16), actor/lib/gui/BarGraph.java
> (1.31), actor/lib/gui/Display.java (1.72),
> actor/lib/gui/InteractiveShell.java (1.28),
> actor/lib/gui/SequenceScope.java (1.29),
> actor/lib/gui/TimedScope.java (1.28), actor/lib/gui/XYScope.java
> (1.26), actor/lib/image/ImageReader.java (1.31),
> actor/lib/image/URLToImage.java (1.27),
> actor/lib/io/DirectoryListing.java (1.37),
> actor/lib/io/LineReader.java (1.30), actor/lib/io/LineWriter.java
> (1.28), actor/lib/logic/Comparator.java (1.24),
> actor/lib/logic/LogicFunction.java (1.37),
> actor/lib/string/StringCompare.java (1.18),
> actor/lib/string/StringFunction.java (1.20),
> actor/parameters/IntRangeParameter.java (1.18),
> actor/parameters/PortParameter.java (1.44),
> data/expr/FileParameter.java (1.31), data/expr/Parameter.java
> (1.119), data/expr/StringParameter.java (1.15),
> data/unit/UnitSystem.java (1.30),
> domains/ct/kernel/CTMixedSignalDirector.java (1.156),
> domains/ct/lib/Integrator.java (1.35),
> domains/de/kernel/DEDirector.java (1.309),
> domains/pn/kernel/PNDirector.java (1.149),
> domains/sdf/kernel/SDFDirector.java (1.145),
> domains/sdf/lib/ArrayToSequence.java (1.54),
> domains/sdf/lib/DotProduct.java (1.44),
> domains/sdf/lib/SequenceToArray.java (1.60),
> vergil/basic/GetDocumentationAction.java (1.25),
> vergil/kernel/attributes/DocumentationAttribute.java (1.21),
> vergil/kernel/attributes/EllipseAttribute.java (1.20),
> vergil/kernel/attributes/ImageAttribute.java (1.27),
> vergil/kernel/attributes/LineAttribute.java (1.20),
> vergil/kernel/attributes/RectangleAttribute.java (1.19),
> vergil/kernel/attributes/ResizablePolygonAttribute.java (1.19),
> vergil/kernel/attributes/TextAttribute.java (1.19): updated all
> documentation so that it uses valid xml. this is required for any
> xml parser to process the documentation.
>
> --------
>
> Hey Kepler devs,
>
> I just spent the last day cleaning up all of the source documentation so
> that it will render correctly when passed through an xml parser. All of
> the ptolemy and kepler source files should now have valid xml in the
> javadocs (with a couple exceptions that I'm still working on). When you
> are documenting code, please make sure that you use valid xml from now
> on in your javadocs. Don't use ampersands (use & instead) and make
> sure you use < and > if you you want a < or > to render. If you
> don't, an xml parser will interpret those as xml tags and will throw
> errors. Also, all tags (including <br>) must be closed! Please do not
> leave open <p> or <li> tags in the documentation. Any line breaks
> (<br>) must use the <br/> notation to close the tag. Also, please use
> lower case tag names and if you do use an upper case tag, close it with
> an upper case. <p></P> is not valid.
>
> Once again, this goes for any javadoc documentation (anything inside a
> /** */ documentation block) either for classes, members or methods.
>
> If everyone keeps their docs clean, it will make parsing documentation
> much easier in the future.
>
> thanks,
> chad
> _______________________________________________
> Kepler-dev mailing list
> Kepler-dev at ecoinformatics.org
> http://mercury.nceas.ucsb.edu/ecoinformatics/mailman/listinfo/kepler-dev
> --------
More information about the Kepler-dev
mailing list