<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>linbox: doc</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.4 -->
<script type="text/javascript">
function hasClass(ele,cls) {
return ele.className.match(new RegExp('(\\s|^)'+cls+'(\\s|$)'));
}
function addClass(ele,cls) {
if (!this.hasClass(ele,cls)) ele.className += " "+cls;
}
function removeClass(ele,cls) {
if (hasClass(ele,cls)) {
var reg = new RegExp('(\\s|^)'+cls+'(\\s|$)');
ele.className=ele.className.replace(reg,' ');
}
}
function toggleVisibility(linkObj) {
var base = linkObj.getAttribute('id');
var summary = document.getElementById(base + '-summary');
var content = document.getElementById(base + '-content');
var trigger = document.getElementById(base + '-trigger');
if ( hasClass(linkObj,'closed') ) {
summary.style.display = 'none';
content.style.display = 'block';
trigger.src = 'open.png';
removeClass(linkObj,'closed');
addClass(linkObj,'opened');
} else if ( hasClass(linkObj,'opened') ) {
summary.style.display = 'block';
content.style.display = 'none';
trigger.src = 'closed.png';
removeClass(linkObj,'opened');
addClass(linkObj,'closed');
}
return false;
}
</script>
<div id="top">
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">linbox</div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="dirs.html"><span>Directories</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<div class="title">doc</div> </div>
</div>
<div class="contents">
<p>This is a discussion of the form and organization of LinBox documentation.
<a href="#details">More...</a></p>
<table class="memberdecls">
</table>
<p>This is a discussion of the form and organization of LinBox documentation. </p>
<p>The doc directory contains</p>
<ul>
<li>in subdirectory linbox-html/ the html documentation, it has been built using <a href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a>. Start at <a href="index.html">linbox-html/index.html</a>.</li>
</ul>
<ul>
<li>Doxyfile, which specifies parameters for Doxygen to use when building the docs.</li>
<li>doc.doxy, which is the source of this page.</li>
<li>mainpage.doxy, which is the source of linbox-html/index.html.</li>
<li><a href="install-dist.html">install-dist.html</a> and <a href="install-dev.html">install-dev.html</a>, some basic installation information.</li>
<li>linbox.html, which can be a handy way to get to linbox-html/index.html.</li>
</ul>
<p>There is a documentation page for each directory (see <a href="modules.html">Modules</a>) and each class of the LinBox distribution. A directory (Module) page discusses the primary concepts supported by codes in the directory and lists the classes declared in the directory's files. A class page discusses properties of the class beyond the primary concept(s) that it implements and lists it's documented members.</p>
<p>Files containing a <code>\file my_dir/my_file.h</code> documentation show up in the <a href="files.html">files</a> list.</p>
<p>Each documented object (directory, class, member function, ...) has a one line memo that appears with it's name or signature in a parent object listing and at the top of it's own page if it has one (directory, class, top-level function). The memo also reappears as the first line of the fuller documentation.</p>
<p>Some attempt is made to indicate which parts are most relevant to the user. <small>HOW??</small></p>
<h4>Developers: </h4>
<p>Here are some rules of thumb about the documentation.</p>
<p>Each directory dir/ has a dir/dir.doxy file listing its most user oriented contents and explaining the general nature of them. All other documentation is in the header files, a doc comment for each class and for each documented member function. In tests/ and examples/ there is also some documentation in .C files.</p>
<p>Each documentation comment begins with a <code>\brief</code> memo. Keep in mind that the <code>\brief</code> text appears with the name/signature line of the object right above it. Thus there is no need to restate information that is plain from the signature such as the C++ type of a parameter. Try to make the brief memo succinctly state what the object is for. The user, looking at the signature and brief memo, will be trying to decide whether, at this moment in her study of things, she needs to click on this item for the fuller documentation of it. Try to help.</p>
<p>The brief memo should not contain links to other pages. Put desired links in the fuller documentation. Most particularly the brief memo should not contain links to the object of which this item is a member. Such links become links to the current page and are a distraction and annoyance to the reader.</p>
<p>Use documented parameter listings, with <code>\param arg - ...</code>, when you have something significant to say about all or most of the parameters. When you use <code>\param</code> for one parameter of a function, use it for all of them. However, it is sometimes better to skip the <code>\param</code> listing format and just discuss in sentences the parameters, their requirements on input, relation to each other, and properties on output. Use your judgement about this on a case by case basis.</p>
<p>Members of archetypes should be thoroughly documented in the archetype and then not documented at all in classes adhering to the archetype. Just a reference to the archetype documentation suffices. See <code>???</code> for an example of this. However, if the archetype function has a particular property concerning it's performance or use in this particular class, then document that special property. See Butterfly for an example of this. In many functions the return value is a reference to the first parameter, the primary output paramater. parameter and is rarely used in practice. In this case, don't use both the <code>\param</code> and the <code>\return</code>. Earlier I proposed not to use <code>\return</code> at all in these situations. Perhaps we should use <code> \return arg1 - ...</code> in place of <code>\param arg1 - ... </code>. See <code>???</code> for an example of this.</p>
<h4>References</h4>
<p>References to papers/book can be documented for classes, functions, groups,... and referenced in a <a href="bib.html">Bibliography</a> page using : <br/>
<code>\ref</code> - [Authors] [<em>Title</em>] [journal,conference,book,...] [<a href="">doi</a>]. </p>
</div>
<hr class="footer"/><address class="footer"><small>Generated on Tue Aug 30 2011 for linbox by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.4 </small></address>
</body>
</html>
