Documentation: Difference between revisions
m
→{{header|Fortran}}
Line 459:
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 outside of text literals. 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 there. 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)
| |||