It's possible to interleave a C++ source file with an HTML document:
//<![IGNORE[
/*]]>
<html>
<head>
<title>Example</title>
</head>
<body>
<p>Example</p>
</body>
</html>
<![IGNORE[*/
#include <iostream>
int main(int argc, char** argv) {
std::cout << "Hello, world!\n";
}
/*]]>
<![IGNORE[*/
//]]>
This leaves a stray // at the start of the HTML document, which can be covered up by wrapping the body content in a <div>:
...
<body>
<div id="main">
</div>
</body>
...
Which is styled to fill the content area with an opaque background:
#main {
background: #ffffff;
left: 0;
position: absolute;
top: 0;
}
Is it a good idea to document code this way? It's more flexibile than, say, Doxygen, but still allows quite structured formats to be used, such as DocBook. It also has the advantage that the source file not only contains the documentation, but is the documentation. Renaming or linking the source file to a filename ending in .htm is enough to make a Web browser read it as HTML.
The only problem is that stray C++ comment at the start of the XML document, which (correct me if I'm wrong) ought to prevent it from validating. Is there any workaround for that?
Edit: Changed to use <![IGNORE[...]]> instead of <!--...--> to avoid clashes with --.