[kepler-dev] Documentation and XML
Christopher Brooks
cxh at eecs.berkeley.edu
Fri Feb 2 08:18:01 PST 2007
Hi Chad,
I've not worked with cvs checkin tests, but I've thought about it a
little. I'm kind of on the fence.
I sort of like the idea of running a formatter each time code is
checked in, but this might require that the user do a cvs update to
get any changes. This could be confusing if you are working
on a file and doing incremental changes, since the file might
change under you between checkins.
I'm a little worried about blocking commits if a file does not pass a
test of some sort though. I think I prefer running batch tests as
part of the nightly build and then periodically doing cleanups. This
is what I do with doccheck and findbugs. Every so often, I take a
look and if someone's code has lots of bugs, I have them fix them, if
there are only a few problems hither and yon, I fix 'em.
Just my $0.02.
_C
--------
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 no
w
> on in your javadocs. Don't use ampersands (use & instead) and ma
ke
> sure you use < and > if you you want a < or > to render. If yo
u
> 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 n
ot
> leave open <p> or <li> tags in the documentation. Any line breaks
> (<br>) must use the <br/> notation to close the tag. Also, please us
e
> lower case tag names and if you do use an upper case tag, close it wi
th
> 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 documentatio
n
> 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