Anonymous user
Documentation: Difference between revisions
Added COBOL, using ROBODoc and/or the Compiler Directive Facility
m (added a ;See also: (bold) header, added another Rosetta Code link (to a related task).) |
(Added COBOL, using ROBODoc and/or the Compiler Directive Facility) |
||
Line 88:
"defn and some other macros allow you add documentation like this. Works the same way"
[])</lang>
=={{header|COBOL}}==
{{works with|ROBODoc}}
ROBODoc allows for documentation extracts from pretty much any language that
allows comments. Includes highlighting of source code. This feature has been
extended for COBOL to allow dashes in names, along with the normal C based
underscore divider. ROBODoc looks for start and end triggers.
Documentation keywords, and comment marker triggers, are managed by
configuration settings and ROBODoc ships with quite a few predefined special
words. Lines after the colon terminated keywords are each extracted into
different paragraph types. Graphviz can also be invoked to include DOT
drawings, images can be embedded, and shell commands can also be invoked during
the HTML generation process.
<lang COBOL>
*>****L* cobweb/cobweb-gtk [0.2]
*> Author:
*> Author details
*> Colophon:
*> Part of the GnuCobol free software project
*> Copyright (C) 2014 person
*> Date 20130308
*> Modified 20141003
*> License GNU General Public License, GPL, 3.0 or greater
*> Documentation licensed GNU FDL, version 2.1 or greater
*> HTML Documentation thanks to ROBODoc --cobol
*> Purpose:
*> GnuCobol functional bindings to GTK+
*> Main module includes paperwork output and self test
*> Synopsis:
*> |dotfile cobweb-gtk.dot
*> |html <br />
*> Functions include
*> |exec cobcrun cobweb-gtk >cobweb-gtk.repository
*> |html <pre>
*> |copy cobweb-gtk.repository
*> |html </pre>
*> |exec rm cobweb-gtk.repository
*> Tectonics:
*> cobc -v -b -g -debug cobweb-gtk.cob voidcall_gtk.c
*> `pkg-config --libs gtk+-3.0` -lvte2_90 -lyelp
*> robodoc --cobol --src ./ --doc cobwebgtk --multidoc --rc robocob.rc --css cobodoc.css
*> cobc -E -Ddocpass cobweb-gtk.cob
*> make singlehtml # once Sphinx set up to read cobweb-gtk.i
*> Example:
*> COPY cobweb-gtk-preamble.
*> procedure division.
*> move TOP-LEVEL to window-type
*> move 640 to width-hint
*> move 480 to height-hint
*> move new-window("window title", window-type,
*> width-hint, height-hint)
*> to gtk-window-data
*> move gtk-go(gtk-window) to extraneous
*> goback.
*> Notes:
*> The interface signatures changed between 0.1 and 0.2
*> Screenshot:
*> image:cobweb-gtk1.png
*> Source:
REPLACE ==FIELDSIZE== BY ==80==
==AREASIZE== BY ==32768==
==FILESIZE== BY ==65536==.
id identification division.
program-id. cobweb-gtk.
...
done goback.
end program cobweb-gtk.
*>****
</lang>
{{works with|GnuCOBOL}}
Another style of auto generated documentation involves the Compiler Directive
Facility and using special defines to mingle documentation blocks within lines
of the source file, which can then be extracted and passed through various
markup processors, like Sphinx ReStructureText or Markdown.
<lang COBOL>
>>IF docpass NOT DEFINED
... code ...
>>ELSE
!doc-marker!
========
:SAMPLE:
========
.. contents::
Introduction
------------
ReStructuredText or other markup source ...
>>END-IF
</lang>
Extraction of documentation segments is feasible using just the Compiler
Directive Facility, but it is usually easier to use '''sed''' or other tools.
Otherwise any Compiler Directives within the documentation become ''live'' and
documentation may trigger other conditional compile statements, usually to bad
effect. In the case of COBOL, this includes both the '''COPY''' and
'''REPLACE''' Text Manipulation keywords, which can easily show up within
documentation segments. It is safer to use an undefined conditional to simply
skip documentation blocks during actual code compilation and extract the
documentation lines with a separate tool before passing the extract to a markup
processor.
=={{header|Common Lisp}}==
| |||