documon
Version:
A documentation system for mortals. Use with any language.
327 lines (205 loc) • 9.9 kB
HTML
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>extract</title>
<meta name="description" content="Extracts comments from a file into an array or mulit-dementional array when the text" arg contains mulitple __package__ or __namepsace__ definitions.">
<!-- Normalize -->
<link rel="stylesheet" href="assets/vendor/normalize.css">
<!-- prettify -->
<link rel="stylesheet" href="assets/vendor/prettify/codamike.css">
<script src="assets/vendor/prettify/prettify.js"></script>
<!-- Documon Pages Info. (Used by various classes to identify this page.) -->
<script>
var pageCtx = {
id : "documon.extract",
name: "extract"
}
</script>
<!-- theme
<link rel="stylesheet" href="assets/fonts/Fira_Sans/FiraSans.css">
<link rel="stylesheet" href="assets/fonts/Inconsolata/inconsolata.css">
-->
<link rel="stylesheet" href="assets/css/pages.css">
<script src="assets/js/documon/Storage.js"></script>
<script src="assets/js/documon/Access.js"></script>
<script src="assets/js/documon/Pages.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-106684927-1', 'auto');
ga('send', 'pageview');
</script>
</head>
<body>
<div class="page">
<div class="main-method">
<a name="methods"></a>
<div class="part-methods">
<a name="documon.extract"></a><a name="extract"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
extract (<span class="method-arguments">text</span>, <span class="method-arguments method-arg-optional">beginDoc</span>, <span class="method-arguments method-arg-optional">endDoc</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/extract.js</span>
<span class="member-line-number">96</span>
</span>
</div>
<div class="member-description">
<div class="meta-block meta-block-klass">
<div class="meta-line"><span class="meta-label" >xpath</span> <span class="meta-target">documon.extract<span></div>
<div class="meta-line"><span class="meta-label" >file</span> <span class="meta-target">documon/src/extract.js<span></div>
</div>
<p>Extracts comments from a file into an array or mulit-dementional array when the "text" arg contains mulitple <strong>package</strong> or <strong>namepsace</strong> definitions.</p>
<p>Each entry in the returned array will be an object containing 3 properties</p>
<ul>
<li><p><strong>start</strong> : The line number that the comment started on</p></li>
<li><p><strong>end</strong> : The line number that the comment ended on</p></li>
<li><p><strong>data</strong> : The contents of the comment</p>
<p>var myComments = extract(str);<br />
yields : [<br />
{ <br />
start : 12,<br />
end : 32,<br />
data : "the descript"<br />
},<br />
{ <br />
start : 12,<br />
end : 32,<br />
data : "the descript"<br />
}<br />
]</p></li>
</ul>
<h2 id="a-few-things-of-note">A few things of note:</h2>
<ul>
<li>The data will NOT include the beginDoc, nor the endDoc strings.</li>
<li>Comment prefixing is stripped <br />
- * [star space]<br />
- tabs<br />
- spaces</li>
<li>Code blocks maintain indentation.</li>
<li>Splitting on <strong>package</strong> or <strong>namespace</strong>. When a single file contains mulitple references to a "<strong>package</strong>" or "<strong>namespace</strong>" comments will split into multiple arrays -- treating the single source file as being mulitple files. </li>
</ul>
<p>Split <strong>Example</strong>:</p>
<pre><code>&#47;**
* Class A
* @package foo <-- this designates a new "page"
*&#47;
&#47;**
* Something for A
* @method something
*&#47;
&#47;**
* Class B
* @package bar <-- this designates a new "page"
*&#47;
&#47;**
* Something for B
* @method something
*&#47;
var myComments = extract(str);
yields : [
[ // the first "page"
{
start : 12,
end : 32,
data : "Class A ... "
},
{
start : 12,
end : 32,
data : "Something for A ..."
},
],
[ // the second "page"
{
start : 64,
end : 96,
data : "Class B ... "
},
{
start : 128,
end : 142,
data : "Something for B ..."
},
,
]</code></pre>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">text</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>the entire file as a string</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">beginDoc</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<span class="flag optional">optional</span>
<span class="default-value">
/**
</span>
<div class="member-description">
<p>The string is used to "open" a comment.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">endDoc</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<span class="flag optional">optional</span>
<span class="default-value">
*/
</span>
<div class="member-description">
<p>The string is used to "close" a comment.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">array</span>
</div>
<div class="member"><p>An array of comments, or multi-dimentional array oaf page comments.</p></div>
</div>
</div>
</div>
</div>
<div class="parts">
</div>
</div>
<div class="footer">Generated by <a href="http://www.documon.net" target="_blank">Documon</a></div>
</body>
</html>