Documentation: Difference between revisions
→{{header|Fancy}}: Add Fortran.
(→{{header|MATLAB}} / {{header|Octave}}: Agh. Correct some details.) |
(→{{header|Fancy}}: Add Fortran.) |
||
Line 449:
Foo docstring println # prints docstring Foo class
Foo instance_method: 'a_method . docstring println # prints method's docstring</lang>
=={{header|Fortran}}==
Fortran offers no language facilities for including documentation within a programme. Being typically a compiled language, the details of the source file (and any documentation that it may contain) are long gone by the time the compiled code is executing. Unlike interpreted languages, it has no access to its "source code" form for self-inspection (or modification!) nor are facilities provided to attach auxiliary information to the components of a programme that might be reported at run time. Except, the NAMELIST facility does enable a code file to read or write variables "by name" in the format <''NameOfVariable''> = <''Value(s)Of Variable''> with a detailed form dependent on the type of the variable, and arrays have a repetition count if successive elements have equal values. This is useful when wishing to write out a complex state, or indeed to read in a complex set of data so as to supply parameters to a run without having to worry over their precise layout.
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 F90 standardised the "escape" comment style whereby everything following an exclamation mark to the end of the line was regarded as a comment. B6700 Fortran used a %-symbol for that. 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. A compiler may produce a "symbol table" identifying the names of all variables, and in the older days, their addresses so that when studying a memory dump there is some hope of discovering what went wrong. But "dump snuffling" is rare these days.
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.
Otherwise, aside from separately-prepared files, the documentation resides in the source file, with layout, choice of names and organised design being the key and subject to style disputes and fashion. One special feature of Fortran is that statement labels can be used to identify logical blocks or sections in a way similar to the numbering of paragraphs in some documents. Labels might be incremented by 100 for sections, 10 for blocks within sections and 1 for stages within sections - even if many labels are never used in the code.
Outside systems are available to assist. It is common for text editors to employ syntax highlighting, but their designers rarely handle the full complexity of Fortran syntax correctly. For instance, the format of a number such as -3.145E+07 is difficult to scan, especially since in Fortran source, spaces are ignored. Then, consider the FORMAT codes, such as <code>31E16.7</code> and similar sequences. More serious efforts scan the Fortran source in order to extract information useful for documentation. There have long been available systems that will identify every routine in a programme and for each identify what routine calls it, and what routines it calls, along with further analysis on their parameters and their usage - this well before F90 introduced the optional INTENT feature. Similarly, within each routine, identify which variables are used where and whether they are read or written. And, analyse the usage of COMMON variables... Likewise, documentation might include a flowchart, and systems exist to produce these as well.
Aside from the Fortran source code alone, there are systems that will also inspect the commentary associated with the code, and, if their conventions are followed (quite reasonable conventions, quoth the designer: declare ''and describe'' each parameter straight away, etc. etc.), will produce for example a .html file with all manner of crosslinkages. For instance, given <lang Fortran> SUBROUTINE FRED(A,N)
REAL*8 A !Distance to the next node.
INTEGER N !Number of the current node.</lang>
Quite useful documentation could be extracted just from that. By mixing actual source statements with the commentary and extracting ''both'', tedious clashes can be reduced, as in <code>CHARACTER*6 T !Three-character name.</code> because a modification to the nature of the parameter had been made, but, the programmer's consciousness faded out as soon as it saw the comment start and noted "non-Fortran source". A system that extracted only the commentary part from that would not give a correct report, whereas with it known that the actual declaration would be included, there would be no longer any need to repeat its details in the comment and the comment could confine itself to meaning and usage.
Similarly, there could be a convention in the file-naming scheme whereby a code file could gain access to its source file, and with further conventions put to use, it could recognise its own messages and nearby find further text with explanations or examples, etc. or indeed find its own manual and print it on request. It is ''much'' better to have one file (and to maintain synchrony within it), than to have two separate files, possibly maintained by two different departments. An accomplished programme might even modify its own source code, say to maintain a version number - if the source code's value matches the compiled-in value then this is the first run of the new version, so increment the counter in the source code. By keeping track of the date and time, and the timestamp of each user's last use, then a user could be advised of changes to the system since their last use. Given that the update log is also within the source file and suitable timestamped.
But none of this is within the Fortran language definition.
=={{header|Go}}==
| |||