Internal Documentation

[eribandogros]

Need both header and method comments. Header comments • What the component is called • Who wrote the component • Where the component fits in the general system design • When the component was written and revised • How the component uses its data structures, algorithms, and control

Example of method then header:

/**
* METHOD
* Iterates over all modules calling sortModuleDescriptorsHelp.
*
* @return sorted module
* @param current: Current module to add to sorted list.
* @throws CircularDependencyException
* @see DependencyResolver#publish(Artifact, File, boolean)
*/
public List sortModuleDescriptors(ModuleInSort current) 

/******************************HEADER************************************/
/*
/* FILE NAME:
/*
/* DESCRIPTION:
/*
/* REFERENCE:
/*
/* DATE BY CHANGE REF DESCRIPTION
/* ======== ======= =========== =============
/* 1/1/2014 Robert Brown 72CF: LS Created the class
/* 1/14/2014 Claire Johns 72CF: LE Added Methd xyz
/*
/*
/*
/**************************************************************************/

[rgulle4]

it looks like this is how it's done in Ruby:

• http://stackoverflow.com/questions/1681467/how-to-document-ruby-code
• or maybe http://yardoc.org/

[rgulle4]

From the rdoc website:

A typical small Ruby program commented using RDoc might be as follows. You can see the formatted result in EXAMPLE.rb and Anagram.

The inline docs below results in Anagram.html, apparently.

# SAUCE: http://rdoc.sourceforge.net/doc/

       # The program takes an initial word or phrase from
       # the command line (or in the absence of a
       # parameter from the first line of standard
       # input).  In then reads successive words or
       # phrases from standard input and reports whether
       # they are angrams of the first word.
       #
       # Author::    Dave Thomas  (mailto:dave@x.y)
       # Copyright:: Copyright (c) 2002 The Pragmatic Programmers, LLC
       # License::   Distributes under the same terms as Ruby

       # This class holds the letters in the original
       # word or phrase. The is_anagram? method allows us
       # to test if subsequent words or phrases are
       # anagrams of the original.
       class Anagram

         # Remember the letters in the initial word
         def initialize(text)
           @initial_letters = letters_of(text)
         end

         # Test to see if a new word contains the same
         # letters as the original
         def is_anagram?(text)
           @initial_letters == letters_of(text)
         end

         # Determine the letters in a word or phrase
         #
         # * all letters are converted to lower case
         # * anything not a letter is stripped out
         # * the letters are converted into an array
         # * the array is sorted
         # * the letters are joined back into a string
         def letters_of(text)
           text.downcase.delete('^a-z').split('').sort.join
         end
       end

       tester = Anagram.new(ARGV.shift || gets)
       ARGF.each do |text|
         puts "Anagram! " if tester.is_anagram? text
       end

[rodomvp]

closing because non-critical... @eribandogros feel free to reopen