Changeset f11c23 for src/documentation/code.dox

Timestamp:

Nov 3, 2011, 10:35:53 AM (13 years ago)

Author:

Frederik Heber <heber@…>

Branches:

Action_Thermostats, Add_AtomRandomPerturbation, Add_FitFragmentPartialChargesAction, Add_RotateAroundBondAction, Add_SelectAtomByNameAction, Added_ParseSaveFragmentResults, AddingActions_SaveParseParticleParameters, Adding_Graph_to_ChangeBondActions, Adding_MD_integration_tests, Adding_ParticleName_to_Atom, Adding_StructOpt_integration_tests, AtomFragments, Automaking_mpqc_open, AutomationFragmentation_failures, Candidate_v1.5.4, Candidate_v1.6.0, Candidate_v1.6.1, ChangeBugEmailaddress, ChangingTestPorts, ChemicalSpaceEvaluator, CombiningParticlePotentialParsing, Combining_Subpackages, Debian_Package_split, Debian_package_split_molecuildergui_only, Disabling_MemDebug, Docu_Python_wait, EmpiricalPotential_contain_HomologyGraph, EmpiricalPotential_contain_HomologyGraph_documentation, Enable_parallel_make_install, Enhance_userguide, Enhanced_StructuralOptimization, Enhanced_StructuralOptimization_continued, Example_ManyWaysToTranslateAtom, Exclude_Hydrogens_annealWithBondGraph, FitPartialCharges_GlobalError, Fix_BoundInBox_CenterInBox_MoleculeActions, Fix_ChargeSampling_PBC, Fix_ChronosMutex, Fix_FitPartialCharges, Fix_FitPotential_needs_atomicnumbers, Fix_ForceAnnealing, Fix_IndependentFragmentGrids, Fix_ParseParticles, Fix_ParseParticles_split_forward_backward_Actions, Fix_PopActions, Fix_QtFragmentList_sorted_selection, Fix_Restrictedkeyset_FragmentMolecule, Fix_StatusMsg, Fix_StepWorldTime_single_argument, Fix_Verbose_Codepatterns, Fix_fitting_potentials, Fixes, ForceAnnealing_goodresults, ForceAnnealing_oldresults, ForceAnnealing_tocheck, ForceAnnealing_with_BondGraph, ForceAnnealing_with_BondGraph_continued, ForceAnnealing_with_BondGraph_continued_betteresults, ForceAnnealing_with_BondGraph_contraction-expansion, FragmentAction_writes_AtomFragments, FragmentMolecule_checks_bonddegrees, GeometryObjects, Gui_Fixes, Gui_displays_atomic_force_velocity, ImplicitCharges, IndependentFragmentGrids, IndependentFragmentGrids_IndividualZeroInstances, IndependentFragmentGrids_IntegrationTest, IndependentFragmentGrids_Sole_NN_Calculation, JobMarket_RobustOnKillsSegFaults, JobMarket_StableWorkerPool, JobMarket_unresolvable_hostname_fix, MoreRobust_FragmentAutomation, ODR_violation_mpqc_open, PartialCharges_OrthogonalSummation, PdbParser_setsAtomName, PythonUI_with_named_parameters, QtGui_reactivate_TimeChanged_changes, Recreated_GuiChecks, Rewrite_FitPartialCharges, RotateToPrincipalAxisSystem_UndoRedo, SaturateAtoms_findBestMatching, SaturateAtoms_singleDegree, StoppableMakroAction, Subpackage_CodePatterns, Subpackage_JobMarket, Subpackage_LinearAlgebra, Subpackage_levmar, Subpackage_mpqc_open, Subpackage_vmg, Switchable_LogView, ThirdParty_MPQC_rebuilt_buildsystem, TrajectoryDependenant_MaxOrder, TremoloParser_IncreasedPrecision, TremoloParser_MultipleTimesteps, TremoloParser_setsAtomName, Ubuntu_1604_changes, stable

Children:

bbff92

Parents:

1e3265

Message:

Added documentation on how to understand the code and its (maybe) future extensions.

File:

• src/documentation/code.dox (modified) (2 diffs)

src/documentation/code.dox

@@ -14 +14 @@
 
 /**
- * \page code How to use the code
+ * \page code How to use and extend the code
+ *
+ * \section code-introduction How to understand the code
+ *
+ * \subsection code-introduction-whats-there What's there already ...
+ *
+ * Generally, you will begin by having to add a certain Action to the code.
+ * Refer to the \ref constructs and (at the very least briefly) go through
+ * all the stuff that is already there. This should give you an idea of what
+ * you do not have to re-invent!
+ *
+ * As soon as you have decided upon all the little things required for your
+ * Action, e.g. you need a LinkedCell construct because of nearest neighbor,
+ * additionally you need access to BondGraph because you need bond distance
+ * information, you want to know how to access and use each of these.
+ *
+ * \subsection code-introduction-whats-not-there What's not there ...
+ *
+ * Not everything is always documented, not everything is always up-to-date.
+ * Search the code or try to look at Actions that are similar to what you
+ * intent. Try to understand how they do and whever your ideas really can't
+ * be realized with the current capabilities of the code.
+ *
+ * If not, it gets more complicated because if one extends the code, one can
+ * proceed in a straight-forward and soon-to-reach-the-goal way or one can
+ * try to realize if one's not generalizing a concept already present and
+ * implement this generalization (and also bring what's already there up to
+ * speed with this new implementation). Of course, before this "refactoring"
+ * (http://en.wikipedia.org/wiki/Code_refactoring) one should have tests in
+ * place that safeguard that the old functionality remains the same, see
+ * \ref tests. From this generalization your concept should then be easier
+ * to implement.
+ *
+ * Last but not least, see \ref future for what some of the areas are where
+ * the code needs extension or refactorization. Maybe somethings close to what
+ * you want and you could do it along the way, at the same time getting to
+ * know the code better?
+ *
+ * \section code-howto-use How to use the code
+ *
+ * There are two things that should make it easy for you to get to know the
+ * constructs, i.e. classes, required for your Action besides the documentation
+ * and serve as tiny examples on how to use them:
+ * - unit tests
+ * - regression tests
+ * 
+ * \subsection code-howto-use-unit-tests Unit tests
+ *
+ * Unit tests give you an idea how to use a specific constructs, e.g. they
+ * tell you where to get it (simply \code new LinkedCell \endcode, or rather
+ * \code World::getInstance().getBondGraph() \endcode, because it's a unique
+ * instance) and how to use them because that's exactly what's being tested
+ * there. Just browse through the various(?) test functions implemented in
+ * each of the unit tests or rather the unit tests to the constructs you need.
+ *
+ * \subsection code-howto-use-regression-tests Regression tests
+ *
+ * Regression tests (\ref tests-regressiontests) give you an idea how your
+ * Action eventually can be called (from the command line), what to put in your
+ * \b .def file and how it ends up being the option you have to give.
+ *
+ * \attention Never forget that you are supposed to add a regression test for
+ * your new Action as well, either right now (http://en.wikipedia.org/wiki/Test-driven_development)
+ * or at the very latest once its finished.
+ *
+ * \subsection code-howto-use-last Last but not least
+ *
+ * Search the code with the desired construct as keyword to find out places
+ * where it is internally used, see how it is done there and do the same
+ * in your own Action.
+ *
+ * \section code-introduction-howto-extend How to extend the code
+ *
+ * Once you're certain your requirements are not met, new classes have to be
+ * added. Do some careful thinking whether you add something altogether new or
+ * whether it's already present in some simpler or slightly other form. In the
+ * latter case, try to generalize what's present and build from there. E.g.
+ * FormatParserParameters have been generalized from a simpler implementation
+ * that was just used for the parameters for MpqcParser (know FormatParser<mpqc>
+ * which has been refactored as well). Don't always go all the way, but extend
+ * and generalize when it makes sense, especially when the code is much easier
+ * to use afterwards or just much more powerful (with immediate consequences).
+ *
+ * Again, refer to \ref future to know what's already on the schedule, i. e.
+ * what's already marked for extension or refactoring.
+ *
+ * \section code-reference Further readings
  *
  * \li \ref faq
@@ -21 +107 @@
  *
  *
- * \date 2011-10-31
+ * \date 2011-11-03
  *
  */