doc: enhanced documentation and references

Signed-off-by: Nick Papior <[email protected]>

INSTALL → INSTALL.md

@@ -1,16 +1,13 @@
-Installation instructions
-*************************
+# Installation instructions  {#installInstructions}
 
-Copyright (C) 2016 Free Software Foundation, Inc.
+- @ref installBasic
+- @ref installAdvanced
+- @ref installSettings
+- @ref installFunctionality
+- @ref installVendor
 
-Copying and distribution of this file, with or without modification,
-are permitted in any medium without royalty provided the copyright
-notice and this notice are preserved.  This file is offered as-is,
-without warranty of any kind.
 
-
-Basic Installation
-==================
+# Basic Installation  {#installBasic}
 
 Building buds is only controlled using the basic Makefiles included.
 Every setting for the compilation and installation can be controlled
@@ -32,81 +29,86 @@ one can do
 
 To _only_ compile the shared library one should do:
 
-   make shared
+    make shared
 
 
 The installation will install either library and the basic buds include
 files in the PREFIX directory.
 
 
-Advanced installation script
-============================
+## Advanced installation  {#installAdvanced}
 
 The actual control of the installation script can be fully controlled in the
 `setup.make` file.
 An assortment of pre-make files are created in the setup.makes directory.
 
 To use one of them you may link it to `setup.make`:
 
-   ln -s setup.makes/static-hard.make setup.make
-   make
+    ln -s setup.makes/static-hard.make setup.make
+    make
 
 which will use the settings for the static library using an aggressive
 optimization strategy.
 
 You may also denote the `setup.make` file using the `SETUP` flag:
 
-   make SETUP=static-hard # or
-   make SETUP=static-hard.make # or
-   make SETUP=setup.makes/static-hard.make
+    make SETUP=static-hard # or
+    make SETUP=static-hard.make # or
+    make SETUP=setup.makes/static-hard.make
 
 To check your current installation setup run this command:
 
-   make show
+    make show
 
 
-Additional settings for the compiler
-------------------------------------
+## Compiler settings  {#installSettings}
 
 Either of these settings may be provided on the `make` command line
 or in `setup.make`.
 In the following 0 means disable while 1 means enable.
 
-PREFIX=<installation prefix>:
-    installation prefix for buds.
+* PREFIX=<installation prefix>:
+
+  installation prefix for buds.
 
-STATIC=1|0:
-    control whether the `libs` target is dependent on the `static` target
+* STATIC=1|0:  
+
+  control whether the `libs` target is dependent on the `static` target
 
-SHARED=0|1:
-    control whether the `libs` target is dependent on the `shared` target
+* SHARED=0|1:
+
+  control whether the `libs` target is dependent on the `shared` target
+
+* OPT=|debug|1|2|3:
+
+  controls the optimization level of the compiler.
+  Debug is the lowest compiler options, 1 is low optimization and
+  3 is the highest optimization.
+
+* VENDOR=gnu|intel|<vendor>:
+
+  use the settings in the vendor/<vendor>.make file for the
+  compiler (see @ref installVendor).
+
+* SETUP=<file>:
 
-OPT=|debug|1|2|3:
-    controls the optimization level of the compiler.
-    Debug is the lowest compiler options, 1 is low optimization and
-    3 is the highest optimization.
+  use the specified file in addition to the `setup.make` file
+  to control the options. The corresponding file will be included in the
+  makefile process right _after_ `setup.make`.
 
-VENDOR=gnu|intel|<vendor>:
-    use the settings in the vendor/<vendor>.make file for the
-    compiler.
+* MPI=0|1:
 
-SETUP=<file>:
-    use the specified file in addition to the `setup.make` file
-    to control the options. The corresponding file will be included in the
-    makefile process right _after_ `setup.make`.
+  control whether the MPI objects should also be added to the library.
+  This enables certain buds only available for MPI installations.
 
-MPI=0|1:
-    control whether the MPI objects should also be added to the library.
-    This enables certain buds only available for MPI installations.
+* OO=1|0:
 
-OO=1|0:
-    control whether the objects are OO so that there exists both regular
-    procedures and the <>%<procedure> calls.
-    This enables object oriented programming.
+  control whether the objects are OO so that there exists both regular
+  procedures and the `<>%%<procedure>` calls.
+  This enables object oriented programming.
 
 
-Controlling the library functionality
--------------------------------------
+# Library functionality  {#installFunctionality}
 
 There are several preprocessor flags for controlling the final
 buds library. Some of them extends the functionality while others
@@ -117,16 +119,18 @@ Currently the preprocessor flags must be added to the CPPFLAGS variable:
 
 Add these to the CPPFLAGS controlling
 
--DBUD_FORTRAN=<integer>:
+* `-DBUD_FORTRAN=<integer>`:
+
     This controls the fortran standard used.
     Currently if <integer> is 2003 or above the basic buds
-    will contain OO functionality as `bud%is_initd()` together
+    will contain OO functionality as `bud%%is_initd()` together
     with the direct function call `is_initd(bud)`.
 
     This is defaulted to 2003 as the majority of compiler vendors
     intrinsically support these extensions.
 
--DBUD_ERROR=<routine name>:
+* `-DBUD_ERROR=<routine name>`:
+
     Controls whether the parent application will provide a
     routine for grabbing errors.
     This routine should be an external routine (not in a module).
@@ -138,13 +142,12 @@ Add these to the CPPFLAGS controlling
 
 
 
-Adding new vendors for compilation
-==================================
+# Compiler vendors  {#installVendor}
 
-The vendor/ directory contains individual files that creates
-defaults for different vendors.
-If you want to enable a new compiler you may copy the vendor/gnu.make
-to vendor/<new>.make and customize the flags to your liking.
+The `vendor` directory contains individual files that creates
+defaults for different vendors.  
+If you want to enable a new compiler you may copy the `vendor/gnu.make`
+to `vendor/<new>.make` and customize the flags to your liking.
 
 Once you have created the vendor file you may use the vendor by compiling
 using:
@@ -156,5 +159,17 @@ Currently only GNU and Intel compiler vendors are supported:
     make VENDOR=gnu # default
     make VENDOR=intel
 
-If you add a new vendor please consider contributing to buds by sending
-the source.
+If you add a new vendor please consider contributing to buds by adding
+a [pull request][buds-pr].
+
+
+
+
+
+<!--
+You need not read below these lines, they are used for the
+documentation
+-->
+
+[buds-pr]: https://github.com/siesta-project/buds/pulls
+

doc/CONTRIBUTORS.md

@@ -1,4 +1,4 @@
-# Contributors
+# Contributors  {#contrib}
 
 buds have been developed by the following list of people:
 
@@ -15,4 +15,13 @@ buds have been developed by the following list of people:
   + Item_Array
   + LL_Array
   + SM_CSR
+  + SM_CSR_C
+  + SM_CSR0
 
+
+# Acknowledgements  {#contribAcknow}
+
+The basic concept of the reference counted mechanisms is inspired by
+the FLIBS project by Arjen Markus as well as minor things from the PyF95 project.
+
+The initial draft of this library was created by Alberto Garcia.

doc/DEV.md

@@ -1,18 +1,22 @@
-# Development of buds
+# Development  {#devel}
+
+- @ref develNotes
+- @ref develNew
+
 
 A short introduction to the buds library and how it may be
 extended can be found in this section.
 
 We highly welcome suggestions, issues and/or bug-fixes.
 Anybody is encouraged to contribute via the github development page:
 
-- [General development repository][buds]
+- [Development repository][buds]
 - [Reporting issues/bugs][issues]
 - [Creating pull-requests for buds][pr]
 
 Please do not hesitate to contribute!
 
-## Notes for developers
+# Notes for developers  {#develNotes}
 
 The library is heavily pasted with pre-processor statements
 which, sadly, is not well-supported in a large range of
@@ -28,7 +32,9 @@ These guide-lines for the code __must__ be followed:
 
 - Pre-processor variables __must__ adhere to these rules:
   1. Prefix with `BUD_` which ensures no name-clashing with
-     parenting libraries/applications.
+  parenting libraries/applications.
+  2. Ensure the implementation files contain an `#undef` statement
+  to limit warnings when compiled.
 
 - All public routines/functions __must__ be interfaced. I.e.
   no routines/functions may be made public.
@@ -56,9 +62,9 @@ These guide-lines for the code __must__ be followed:
 		end interface
 ~~~~~~~~~~~
 
-  + Prefer to add contribution statements in the CONTRIBUTORS.md file
+  + Add contribution statements in the `CONTRIBUTORS.md` file
 	which ensures a resulting documentation to be short and concise.  
-    In the CONTRIBUTORS.md file you may add any information and specifics
+    In the `CONTRIBUTORS.md` file you may add any information and specifics
 	of what has been implemented by specific authors.
   + Do __not__ use the `\@date` marker as it clutters the documentation.
   + Use `\@opt` to denote optional arguments, for instance:
@@ -88,7 +94,7 @@ These guide-lines for the code __must__ be followed:
   function name as a local variable.  
   It also helps understanding the code *in-line*.
 
-## Creating a new bud
+# Creating a new bud  {#develNew}
 
 A short description of the required steps needed to
 create a custom bud type is listed here:
@@ -153,12 +159,6 @@ create a custom bud type is listed here:
    that name-clashes are never encountered.
 
 
-## Acknowledgements
-
-The basic concept of the reference counted mechanisms is inspired by
-the FLIBS project by Arjen Markus as well as minor things from the PyF95 project.
-
-The initial draft of this library was created by Alberto Garcia.
 
 
 [buds]: https://github.com/siesta-project/buds

doc/DOWNLOAD.md

@@ -0,0 +1,18 @@
+# Download  {#download}
+
+The __buds__ library may be downloaded from the development Github page [here][buds-hp].
+
+The current release can be found here:
+
+- [0.1.tar.gz][buds-currel]
+
+Previous releases can be found [here][buds-rels] but they are not
+supported.  
+If you encounter any problem you _should_ first try and update to the latest version before an issue is raised at [issue-tracker][buds-issue].
+
+
+
+[buds-hp]: https://github.com/siesta-project/buds
+[buds-issue]: https://github.com/siesta-project/buds/issues
+[buds-currel]: https://github.com/siesta-project/buds/archive/0.1.tar.gz
+[buds-rels]: https://github.com/siesta-project/buds/releases

doc/Doxyfile

@@ -780,7 +780,7 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = doc src include
+INPUT                  = doc src include INSTALL.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

doc/README.md

@@ -1,21 +1,47 @@
-# buds {#buds}
+# Welcome to buds  {#mainWelcome}
 
-This library implements a generic interface for creating
-reference counted variables which enables easy garbage-collection
-for variables without worrying about copying data.
+__Welcome to the documentation of buds BUDS_VERSION.__
+
+# Introduction  {#mainIntroduction}
+
+Implementation of generic interface for creating
+reference counted variables.  
+Reference counted variables enables garbage-collection
+for variables with the added benefit of never having to
+dublicate data.
 
 This is useful when using data-types/objects which you do not know
-when to delete because of depedencies.
+when to delete because of unknown depedencies.
+
+## Documentation  {#mainDocumentation}
+
+- @subpage installInstructions
+  - @ref installBasic
+  - @ref installAdvanced
+  - @ref installSettings
+  - @ref installFunctionality
+  - @ref installVendor
+
+- @subpage download
+
+- @subpage devel
+  - @ref develNotes
+  - @ref develNew
+
+
+- @subpage contrib
+  - @ref contribAcknow
+
 
-## Generic interface {#budsGenericInterface}
+## Generic interface  {#budsGenericInterface}
 
 The basic buds-library adds certain files which are useful for creating
 custom reference counted types using a standard. buds may be installed
 in the most basic format which _only_ adds the interfaces for creating
 custom data types. buds may be used in this minimal form.
 
 
-## The standard bud library {#budsStandardLibrary}
+## The standard bud library  {#budsStandardLibrary}
 
 In addition to the generic interfaces buds implements a selection of
 data-types which have been encountered in the development of a density
@@ -25,7 +51,7 @@ generic interfaces.
 You are encouraged to scour the documentation to find possible compatible
 reference counted data types that you may find useful.
 
-## Contributing {#budsContributing}
+## Contributing  {#budsContributing}
 
 We encourage contribution, be it data-type suggestions and/or pull-requests.