Difference between revisions of "GENIE Using NaturalDocs"

From SourceWiki
Jump to navigation Jump to search
m (→‎Intro: make doc -> make docs)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
==Intro==
 
==Intro==
  
NaturalDocs (http://www.naturaldocs.org/) is a very useful package that turns ordinary code comments into professional looking HTML documentation.  In GENIE, if you type '''make doc''', NaturalDocs will scan the whole repository for suitable comments and do the do.  See '''genie-main/doc/index.html''' for the result.
+
NaturalDocs (http://www.naturaldocs.org/) is a very useful package that turns ordinary code comments into professional looking HTML documentation.  In GENIE, if you type '''make docs''' when in genie-main, NaturalDocs will scan the whole repository for suitable comments and do the do.  See '''genie-main/doc/index.html''' for the result.
  
Rest assured, NaturalDocs '''will not''', I'll repeat that, '''will not''' drag every murky comment you make kiccking and screaming out into the lime light.  Your comments need to be in a particular format.  Happily, this format is far from onerous and is, in fact, very ''natural'' (your saying "ah" about now..).  The section below shows just how easy using NaturalDocs can be.
+
Rest assured, NaturalDocs '''will not''', I'll repeat that, '''will not''' drag every murky comment you make kicking and screaming out into the lime light.  Your comments need to be in a particular format.  Happily, this format is far from onerous and is, in fact, very ''natural'' (your saying "ah" about now..).  The section below shows just how easy using NaturalDocs can be.
  
 
==Quickstart==
 
==Quickstart==
Line 53: Line 53:
  
 
To learn more about making your comments compatible, go to http://www.naturaldocs.org/documenting.html, especially the page showing which keywords you can use, http://www.naturaldocs.org/keywords.html.
 
To learn more about making your comments compatible, go to http://www.naturaldocs.org/documenting.html, especially the page showing which keywords you can use, http://www.naturaldocs.org/keywords.html.
 +
 +
==What it looks like==
 +
 +
[[Image:NaturalDocs2.JPG|frame|centre|Professional quality documentaion from NaturalDocs]]

Latest revision as of 18:11, 9 October 2008

Intro

NaturalDocs (http://www.naturaldocs.org/) is a very useful package that turns ordinary code comments into professional looking HTML documentation. In GENIE, if you type make docs when in genie-main, NaturalDocs will scan the whole repository for suitable comments and do the do. See genie-main/doc/index.html for the result.

Rest assured, NaturalDocs will not, I'll repeat that, will not drag every murky comment you make kicking and screaming out into the lime light. Your comments need to be in a particular format. Happily, this format is far from onerous and is, in fact, very natural (your saying "ah" about now..). The section below shows just how easy using NaturalDocs can be.

Quickstart

Here is a quick and easy example showing how you can immediately get going using NaturalDocs:

MODULE mymodule

  ! File: mymodule.f90
  !
  ! Description:
  !
  ! A module containing some pretty useful stuff for use with widgets.

  ! var: koverall
  ! An important variable that I would like to document.

  integer :: koverall 

  contains:

    !  Subroutine: Multiply
    !
    !  Multiplies two integers.
    !
    !  Input:
    !
    !    x - The first integer.
    !    y - The second integer.
    !  
    ! Input/Output:   
    !
    ! Output:
    !
    !    z - The integer which results from the multiplication. 

    subroutine Multiply (x, y, z)

      integer, intent(in)  :: x
      integer, intent(in)  :: y
      integer, intent(out) :: z
 
      z = x * y

    end subroutine
end MODULE

To learn more about making your comments compatible, go to http://www.naturaldocs.org/documenting.html, especially the page showing which keywords you can use, http://www.naturaldocs.org/keywords.html.

What it looks like

Professional quality documentaion from NaturalDocs