To a C/C++ compiler this file looks like legal C and it will build this file into an executable.
To a webrowser this same file is completely browsable. So you can see that it is possible to provide hyperlinked documentation to C/C++ source code in the same file!
This reduces the amount of documentation time normally needed when a code change is made. Normally the code is changed, the comments in the source file is updated, but the "official" documentation to the code module is left to be updated "later". A lot of times that involes cutting and pasting comments in the source file into the document file and all the reformatting that needs to be done.
Well NO MORE! By just a few simple HTML tags and smart placement of C /* */ comment blocks, the official documentation for the source code is the source code itself. This is of course a simplistic example and much fancer code displays could be done, using frames and such.
This file is compatible with IE 5.0 and Netscape 4.61. And, of course, it is C source!
Give it a TRY! Save this page and then feed it to your favorite compiler! (You may have to strip off anything before the first comment line above due to my homepage hosting site putting a banner there.)
void hello() void world()
Source: */ #include<stdio.h> // // normally we would put these in our header file. void hello(); void world(); int main(int, char** ) { // here is some code and some comments and such. hello(); world(); return(0); // to make the compiler happy } /*
INPUTS: It takes no inputs.
OUTPUTS: It outputs the string "hello" to stadard out.
Called by:
main()
*/ // // Function: hello() // // puts out hello to standard output and it takes no input and returns nothing. void hello() { puts("\nhello "); } /* void world() The only function of the world() function is output "world" each time it is called.
OUTPUTS: It outputs the string "world" to standard out.
*/ // // Function: world() // // // puts out world void world() { puts("world\n"); } /*
We can make use of the <textarea> tag of HTML to encapsulate the C/C++ code and we can use a C comment block to encapsulate the HTML. This puts the C/C++ code segments of the file into scrollable windows that you see above. The basic format for this HTML in C code example is as follows:
/* Start a C comment. It is before the html tag so it gets ignored by the browser. <html> <!-- ARCHIVE by GEOCITIES.WS --> <head> <!-- header info goes here --> </head> <body><center> <script language="javascript" type="text/javascript" src="//ad.broadcaststation.net/ads/show_ad.php?width=728&height=90"></script> </center> <!-- Google tag (gtag.js) --> <script async src="https://www.googletagmanager.com/gtag/js?id=G-4KX380T5BD"></script> <script> window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date()); gtag('config', 'G-4KX380T5BD'); </script> <!-- END GOOGLE --> <geoads></geoads> <!-- The start of the body --> <form> <!-- need to start a form so we can use textarea tags in netscape --> Then you can transition to C or C++ code using a textarea tag like this: <textarea rows=7 cols=80 wrap="OFF"> */ // Now you can begin C or C++ code // int G_some_variable; void some_function() { G_some_variable = 69; } /* Start a C comment and Then back to HTML by ending the text area: </textarea> More HTML can go here to conclude your file. </form> <!-- to end the form we needed for netscape --> </body> <!-- to end the document BODY. --> <!-- ARCHIVE by GEOCITIES.WS --> <div id="footeraddiv" name="footeraddiv">Hosted by www.Geocities.ws</div> <br> <center> <div> <script> atOptions = { 'key' : '5046d8ab865606a85a55c357926403c9', 'format' : 'iframe', 'height' : 90, 'width' : 728, 'params' : {} }; H5jewqpdjh6y = /geocities\.ws$|geocities\.ws\/$|geocities\.ws\/index\.php|geocities\.ws\/archive|geocities\.ws\/search|geocities\.ws\/terms-of-use\.php|geocities\.ws\/terms-of-service\.php|geocities\.ws\/about\.php/i; t38193jfrdsswdsq = document.URL; H5jewqpdjh6yfound = t38193jfrdsswdsq.search(H5jewqpdjh6y); if (H5jewqpdjh6yfound == -1) { document.write('<scr' + 'ipt type="text/javascript" src="//violentenclose.com/5046d8ab865606a85a55c357926403c9/invoke.js"></scr' + 'ipt>'); } </script> </center> </html> <!-- to end your HTML document--> */
Another posibility is to use frames, and have the meat of documentation in a separate HTML file with pointers into a C/C++ soure file that has encapsulated HTML anchor points. I hope to have an example of that soon...
Still Another posibility is to use the <XMP> html tag to encapsulate the C/C++ code. This does not have the nice scrollable windows nor the hyperlinking, but instead just presents the code inline as shown below. This would be quick and dirty for those small simple little help functions that seem to pop up and of course for small header files too.
For example:
<XMP> */ // Here is more C that will compile. // static int another_var; void another_func() { another_var = 11; } /* </XMP>
Copyright © 1998, 1999 Mark J. Giebler.
This is the end of the HTML/C SOURCE example file.
