Re: Will the availability of browsers affect source code?

crb@eng.umd.edu (Christopher R. Bowman) writes:
>With the availability of multiple cross plattform world wide web browsers
>will we see any impact on how programs are coded and commented?
>[...]
>Will language>design change as a results of any of this?


Well, Sun's new language Java, which was designed to be a language which
can be safely run in web browsers, has a special comment form from which
documentation can be automatically generated.


The contents of the comment are, by convention, in HTML, along with
some other markup with a different syntax. The documentation generator
makes a set of web pages with cross references as anchors, etc, using
other imbedded commands. The comment is actually part of the language
rather than just a thing the lexer strips out, because it's only
syntactically valid before declarations.


For example


/** <- this is a special documentation comment
  *
  * This is a foobar, which blats. <strong>Never</strong>
  * gwimple it with a blotz. <p>
  * After blatting, we glorp appropriately. Make sure
  * this is synced with <a href="random/design.html">the
  * design</a>.
  *
  * @see gwimple
  * @see blotz.blats
  * @see glorp
  * @author Rundermeyer Jr. <rj@gwunk.org>
  * @version 1.23, 12 Aug 1970
  */
class foobar extends meta_variable_Y {
...
}


This will cause "javadoc" to generate a piece of HTML for this class
in a structured document containing all the other classes in a package,
complete with generated cross references, etc. There are @ keywords
for documenting things like return values, arguments, exceptions
thrown, etc.


I'm not quite sure about what happens to all the block comment '*'s,
but Sun's source has them and they don't appear in the documentation,
so I assume that javadoc strips them out in some automagic way.


It's interesting that this is in some ways similar to literate
programming tools, but approached from the other direction (imbedded
documentation with markup, rather than imbedding the program in marked
up documentation).


(A random aside: it seems to me that compiler writers are using
literate programming tools more than other classes of programmers. Is
this because compilers are inherently complex? Because I spend more
time with compilers than other code? Because they all want to publish
books? :-)


Despite all this, I think the overall quality of comments won't be
improved just by having more powerful mechanisms.


J
--

Return to the comp.compilers page.
Search the comp.compilers archives again.