@ciao-lang/ts-ciao-interface
Version:
Simple Ciao interface for node.
29 lines (26 loc) • 7.05 kB
HTML
<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><meta name="theme-color" content="#273f79"/><link rel="stylesheet" href="lpdoc.css" type="text/css"/><script type="text/javascript" src="lpdoc.js"></script><title>Documentation comments — The Ciao System v1.22</title></head><body><div class="lpdoc-page fixleftbar"><a href="#" id="sidebar-toggle-button" class="lpdoc-navbutton"><span id="sidebar-button-arrow">☰</span></a><div id="sidebar" class="lpdoc-sidebar"><div style="height: 40px; margin-left: auto; margin-right: auto"><img src="ciao-logo_autofig.png" width=auto height=100%></div><div class="lpdoc-nav"><span class="lpdoc-on-right"><a class="lpdoc-navbutton" href="AssrtLang.html">↑</a><a class="lpdoc-navbutton" href="basicmodes_doc.html">←</a><a class="lpdoc-navbutton" href="ExtendLang.html">→</a><a class="lpdoc-navbutton" href="ciaosearch.html">🔍</a></span><span><a href="ciaofulltoc.html">TOC</a></span></div><hr></hr><ul class="lpdoc-itemize-sectpath"><li><a href="ciao.html">The Ciao System</a> »<br/> </li><li><a href="AssrtLang.html">PART III - Assertions and auto-documentation</a> »<br/> </li><li><a href=""><strong>Documentation comments</strong></a></li></ul><hr></hr><em>ON THIS PAGE</em><ul><li><a href="#Documentation comments as terms">Documentation comments as terms</a></li><li><a href="#Relation with comment assertions">Relation with comment assertions</a></li><li><a href="#Usage and interface">Usage and interface</a></li></ul></div><div class="lpdoc-main"><div id=""><h1>Documentation comments</h1><a class="lpdoc-idx-anchor" href="ciaosearch.html#doccomments"></a>
<strong>Author(s):</strong> <a class="lpdoc-idx-anchor" id="Jose F. Morales" href="ciaosearch.html#Jose F. Morales">Jose F. Morales</a>, <a class="lpdoc-idx-anchor" id="Manuel Hermenegildo" href="ciaosearch.html#Manuel Hermenegildo">Manuel Hermenegildo</a>.<p>
<div class="lpdoc-alert"><strong>Stability: [</strong><strong>devel</strong><strong>] </strong>This is still a beta version for experimentation. Much functionality is implemented but syntax may change in the future.</div><p><br/>
This package allows including machine-readable documentation (including assertions) inside code comments. Additionally, a simpler lightweight markup syntax is enabled for (<a class="lpdoc-idx-anchor" id="0" href="ciaosearch.html#LPdoc"><tt>LPdoc</tt></a>) documentation.<p>The overall objective is to allow speeding up the process of documentation for many cases that do not require the full power of the documentation system and assertion language, as well as improving the portability (as documentation comments are simply ignored when not supported by other Prolog systems).<p>The syntax is partially inspired in the mark up syntax for <a href="http://www.stack.nl/~dimitri/doxygen/markdown.html">Doxygen</a>, <a href="http://coq.inria.fr/doc/Reference-Manual018.html#toc97">Coqdoc</a>, and <a href="http://www.haskell.org/haddock/doc/html/ch03s08.html">Haddock</a>.<p><div id="Documentation comments as terms"><h2>Documentation comments as terms</h2> <p>This package enables grammar extensions that allow some special operators, which annotate the source code with documentation, are then translated as <em>documentation assertions</em>.<p>The following pieces of text are understood as both prefix or postfix operators:<p><pre class="lpdoc-codeblock"><tt>%!</tt> <em>Comment</em> (or) <tt>/*!</tt> <em>Comment</em> <tt>*/</tt>
<tt>%</tt> <em>...</em>
</pre> <p>which is used to write arbitrary chunks of documentation (usually referring to the code after them).<p><pre class="lpdoc-codeblock"><tt>%<</tt> <em>Comment</em> (or) <tt>/*<</tt> <em>Comment</em> <tt>*/</tt>
<tt>%</tt> <em>...</em>
</pre> <p>which is used to write chunks of documentation (usually referring to the code before them).<p>Comments appear in the abstract syntax tree of the parsed programs as special terms. The <a class="lpdoc-idx-anchor" id="1" href=""><tt>doccomments</tt></a> package extracts them from the program to generate the documentation.<p>Note that reading comments symbolically requires cooperation with the internal parsing routines. For more details, see the <tt>doccomments</tt> Prolog flag and its use in the <a class="lpdoc-idx-anchor" id="2" href="read.html"><tt>read</tt></a> and <a class="lpdoc-idx-anchor" id="3" href="tokenize.html"><tt>tokenize</tt></a> modules.<p><div class="lpdoc-note"> As <tt># "..."</tt> comments in LPdoc, this approach continues the <em>documentation in the AST</em>. Other systems take a similar approach (for example, see <a href="http://docs.racket-lang.org/scribble/text.html">Scribble</a>). A simpler approach could just parse documentation in one pass and generate clean code. It is not clear which one is better in the long term. </div> <p></div><div id="Relation with comment assertions"><h2>Relation with comment assertions</h2> <p>This package allows using an alternative syntax for machine-readable comments. Essentially, most comments of the form:<p><pre class="lpdoc-codeblock">:- doc(<em>CommentType</em>,<em>Body</em>).
</pre> <p>can be written as:<p><pre class="lpdoc-codeblock"><tt>%!</tt> @<em>CommentType</em> <em>Body</em>
</pre> <p><em>Body</em> can expand over several lines but each must have a <tt>%</tt> in the first column. For example, the following:<p><pre class="lpdoc-codeblock">%! @title A nice module
%
% @author Pro Grammer
%
% @module This is a very nice module indeed.
% It can be used for several purposes.
%
% @hide internal/3
</pre> <p>is equivalent to:<p><pre class="lpdoc-codeblock">:- doc(title, "A nice module").
:- doc(author,"Pro Grammer").
:- doc(module,"This is a very nice module indeed.
It can be used for several purposes.").
:- doc(hide,internal/3).
</pre> <p>See files distributed at <tt>markdown/examples/</tt> for more examples. </div><br/><div id="Usage and interface"><h2>Usage and interface</h2><div class="lpdoc-cartouche"><ul><li><strong>Library usage:</strong><br/><tt>:- use_package(doccomments).</tt>
or
<tt>:- module(...,...,[doccomments]).</tt><li><strong>Implicit imports:</strong><br/><ul class="lpdoc-itemize-minus"><li><em>Packages:</em><br/><a class="lpdoc-idx-anchor" id="4" href="ciaosearch.html#prelude"><tt>prelude</tt></a>, <a class="lpdoc-idx-anchor" id="5" href="ciaosearch.html#initial"><tt>initial</tt></a>, <a class="lpdoc-idx-anchor" id="6" href="condcomp_doc.html"><tt>condcomp</tt></a>, <a class="lpdoc-idx-anchor" id="7" href="assertions_doc.html"><tt>assertions</tt></a>, <a class="lpdoc-idx-anchor" id="8" href="ciaosearch.html#assertions/assertions_basic"><tt>assertions/assertions_basic</tt></a>.
</ul></ul></div></div></div><div class="lpdoc-footer">Generated with LPdoc using Ciao</div></div><div class="lpdoc-clearer"></div></div></body></html>