[kepler-dev] Documentation and XML

Fri Feb 2 07:00:08 PST 2007

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 &amp; instead) and make 
    sure you use &lt; and &gt; 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
--------