Action #0039 | Write up use case for modularize...

["Jeremy Ralph [DITA SIDSC]" <jralph-sidsc@productive-eda.com>]

I've prepared the attached txt file in an attempt to show how the concept of
object oriented inheritance might be used to have a base set of elements for
Component, MemoryMap, AddressBlock, Register, and BitField.  I'm not sure
how this type of inheritance relationship would be specified in a DTD and
DITA specialization. The attached file also lists some benefits and XML
examples.
 
Cheers,
  Jeremy




--
Jeremy Ralph
PDTi      :: http://www.productive-eda.com
SpectaReg :: http://www.productive-eda.com/SpectaReg
Spec-down code and doc generation for register interfaces

  
 
 
 
 
  
Contributed to DITA-SIDSC by Jeremy Ralph of PDTi on 2007-11-12 

This attempts to show how the concept of object oriented inheritance might be used to have a base set of elements for Component, MemoryMap, AddressBlock, Register, and BitField.  I'm not sure how this inheritance relationship would be specified in a DTD and DITA Specialization.    
 
----------------------
Class Structure
----------------------

BaseObject
+ has a name
+ has a description
+ has a briefDescription

Component extends BaseObject
+ contains MemoryMaps

MemoryMap extends BaseObject
+ contains AddressBlocks

AddressBlock extends BaseObject
+ contains Registers

Register extends BaseObject
+ contains BitFields

BitField extends BaseObject


If each instance of BaseObject is mapped to it's own topic then I don't think there would be an issue. However, if BitField is not specified as its own topic but is specified in a Register topic then there would be two different name elements in a single Topic which may cause some issues.  One advantage with having a BitField as its own topic is that it is easier to move BitFields between registers (a common use-case) and re-use BitFields between different projects in different registers.  

------------------------------------------
Benefits of this inheritance relationship:
------------------------------------------
1) centralized processing of the abstract BaseObject level (code reuse)
2) ability to change the definition of all BaseObjects in one central location (for example adding an id member/element) 
--------------------------------------------
Example 1) XML using abstract naming method.
This would be mapped into several topics.
-------------------------------------------

<component>
  <name>SomeComponent</name>
  <description>This is a great Component.</description>
  ...
  <memoryMap>
    <name>SomeMemoryMap</name>
    <description>This is a great MemoryMap</description>
    ...
	  <addressBlock>
	    <name>SomeAddressBlock</name>
	    <description>This is a great AddressBlock</description>
			...
		  <register>
		    <name>SomeRegister</name>
		    <description>This is a great Register</description>
				...
			  <bitField>
			    <name>SomeBitField</name>
			    <description>This is a great BitField</description>
					...
				</bitField>
			</register>
		</addressblock>
	</memoryMap>
</component>

----------------------------------------------------
Example 2) XML using context specific naming method.
Again mapped into several topics.
---------------------------------------------------

<component>
  <componentName>SomeComponent</componentName>
  <componentDescription>This is a great Component.</componentDescription>
  ...
  <memoryMap>
    <memoryMapName>SomeMemoryMap</memoryMapName>
    <description>This is a great MemoryMap</description>
    ...
	  <addressBlock>
	    <addressBlockName>SomeAddressBlock</addressBlockName>
	    <addressBlockDescription>This is a great AddressBlock</addressBlockDescription>
			...
		</addressblock>
	</memoryMap>
</component>