yade-dev team mailing list archive

[Václav Šmilauer <eudoxos@xxxxxxxx>]

Hi everybody,

I would like to ask responsible persons to use new macros (instead of
REGISTER_ATTRIBUTES, YADE_CLASS_AND_BASE, REGISTER_CLASS_NAME,
REGISTER_BASE_CLASS) to register their classes. The list of classes that
don't use them yet is shown on screen every time yade runs (copied
below).

PLEASE do this _really_, those classes will not be functional in python
otherwise soon; also they don't have any documentation generated.

Take it as an opportunity to properly document all attributes (thing
TriaxialTest), to avoid frequent questions on the mailing list ;-)

I added some documentation on those macros in Serializable.hpp, but also
have a look at classes that already use them (e.g. ElasticContactLaw,
https://www.yade-dem.org/sphinx/yade.wrapper.html#yade.wrapper.ElasticContactLaw). I am adding the text from Serializable.hpp here. Let me know if there are questions.

Thanks for cooperation.

Vaclav

----

/* Macros for registering classes in python, serialization framework,
class factory. These macros create default (parameterless) constructor,
declare all attributes (delete those from the class elsewhere) and
initialize them at construction time.

Each part of macro name is one argument you have to provide:

CLASS: class name (without quotes)
BASE: base class name (without quotes)
DOC: docstring for this class (quoted; uses the special text syntax, see
below)
ATTRS: list of attributes ((type,attributeName,defaultValue,"documentation for the attribute"))
	type is c++ type
	attributeName: the identifier name; it will appear under the same name in python
	defaultValue: value that will be set by the default ctor; can be empty. Is automatically documented.
	documentation: arbitrary string, NOT EMPTY. Can contain the following strings (including the |pipes|):
		|yupdate| will expand to (updated automatically); use for attributes that are, well, updated automatically at every step for instance
		|ycompute| will expand to (computed automatically); use for attributes that are computed (at the beginning, for instance, and there is no point in setting them)
		[m²]: specify dimensions for all attributes where this is appropriate
CTOR: what should be run in the default ctor; for some classes, this will be createIndex();, mostly it will be nothing
PY: extra initializations for python, mostly nothing
INIT: sequence of ((attribute,value)) to be intiialized with the default ctor; useful for initialization of references or constants, which cannot be done in the ctor

Pick the simplest macro you need (equivalent to passing empty
arguments):

YADE_CLASS_BASE_DOC
YADE_CLASS_BASE_DOC_ATTRS
YADE_CLASS_BASE_DOC_ATTRS_CTOR
YADE_CLASS_BASE_DOC_ATTRS_CTOR_PY
YADE_CLASS_BASE_DOC_ATTRS_INIT_CTOR_PY

documentation text syntax
-------------------------
Erite plain text. Paragraphs are separated by empty lines (\n\n in c++
strings). Use hyperlinks abundantly in both class and attribute
documentation, with the special :yref:`target` syntax: :yref:`Body` will
expand to hyperlink to the Body class
documentation, :yref:`dynamic<Body::dynamic>` will the hyperlink to
Body::dynamic, but text will show 'dynamic'.

(Note: for classes with static data members (Gl1_*), there is a special
YADE_CLASS_BASE_DOC_STATICATTRS. Those mentioned above will not do.)

*/

----
Welcome to Yade bzr2021
FIXME: class CSPhys does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class CapillaryPressureEngine does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class CapillaryRecorder does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class CapillaryStressRecorder does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class CohesiveFrictionalContactInteraction does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class CohesiveFrictionalContactLaw does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class CohesiveFrictionalMat does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class CohesiveFrictionalRelationships does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class CohesiveTriaxialTest does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class ContactStressRecorder does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class GlobalStiffnessTimeStepper does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class HydraulicForceEngine does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class Ig2_Facet_Sphere_ScGeom does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class Ig2_Sphere_Sphere_ScGeom does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class Ip2_2xCohFrictMat_NormalInelasticityPhys does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class Ip2_BMP_BMP_CSPhys does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class Ip2_FrictMat_FrictMat_FrictPhys does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class Ip2_MomentMat_MomentMat_MomentPhys does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class Ip2_SimleViscoelasticMat_SimpleViscoelasticMat_SimpleViscoelasticPhys does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class Law2_Dem3Dof_CSPhys_CundallStrack does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class Law2_SCG_MomentPhys_CohesionlessMomentRotation does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class Law2_Spheres_Viscoelastic_SimpleViscoelastic does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class MomentEngine does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class MomentPhys does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class NormalInelasticityLaw does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class NormalInelasticityPhys does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class PositionOrientationRecorder does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class ResetRandomPosition does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class SimpleElasticRelationshipsWater does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class SimpleViscoelasticMat does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class SimpleViscoelasticPhys does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class TriaxialCompressionEngine does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class TriaxialStateRecorder does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class TriaxialStressController does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class TriaxialTest does not register with YADE_CLASS_BASE_DOC_ATTR* yet
FIXME: class TriaxialTestWater does not register with YADE_CLASS_BASE_DOC_ATTR* yet