Documentation: Difference between revisions

Line 575:

====In the source file====

Thus, documentation depends on whatever the programmer sees fit to provide in the source file, possibly under protest. Originally, only "block" comments could be provided, signified by a C in column one (and in some extensions, a letter D in column one signified "debugging" statements that would be compiled in or not according to the setting of a compiler option), however this vertical alternation of layers of code and commentary can be obstructive to the reader. F90 standardised the "escape" comment style whereby outside a text literal, everything following an exclamation mark to the end of the line was regarded as a comment (B6700 Fortran used a %-symbol), thus code and commentary can be arranged in two non-clashing columns. There is no comment start - comment stop facility as with {blah} in Pascal or /*blah*/ in pl/i, etc. and compilers may or may not recognise non-Fortran control lines such as $Omit or similar.

Thus, documentation depends on whatever the programmer sees fit to provide in the source file, possibly under protest. Originally, only "block" comments could be provided, signified by a C in column one (and in some extensions, a letter D in column one signified "debugging" statements that would be compiled in or not according to the setting of a compiler option), however this vertical alternation of layers of code and commentary can be obstructive to the reader. F90 standardised the "escape" comment style whereby outside a text literal, everything following an exclamation mark to the end of the line was regarded as a comment (B6700 Fortran used a %-symbol), thus code and commentary can be arranged in two non-clashing columns - especially if the source is listed via a reformatting system with that in mind. There is no comment start - comment stop facility as with {blah} in Pascal or /*blah*/ in pl/i, etc. and compilers may or may not recognise non-Fortran control lines such as $Omit or similar.

Fortran 90 also introduced the ability to specify INTENT IN, OUT, or INOUT for parameters to routines, as well as the usual type indications. Its MODULE protocol includes an INTERFACE specification to assist in the description of collections of functions or subroutines with different types and numbers of parameters. These change what the compiler allows or rejects, but are also often important parts of documentation.