[Mono-docs-list] Proposed human-readable XML

John Barnette jbarn@httcb.net
Mon, 11 Mar 2002 21:10:22 -0700


--=====================_63669311==_
Content-Type: text/plain; charset="us-ascii"; format=flowed

Guys,

Attached is an example of XML documentation in a form that I'd like to use 
for all our human-editable API docs.  A couple of advantages:

* Understandable enough to hand-edit
* Contains (almost) no information duplicated in assembly metadata
* Shares many tags and conventions with the XML documentation schema
   described in the ECMA C# standard (translation back and forth will
   be trivial)

Thoughts, please.  If this is worthwhile (and I get a response from the 
list ;-), an XSD, tag manual, stub generator, and translators to/from the 
csc generated output style will follow as quickly as I can crank 'em out.


~ j. // Oh, and the example (Graphics.Point) is the same one used in
      // the ECMA spec if you'd like to compare.
--=====================_63669311==_
Content-Type: application/xml; name="human-doc-1.xml"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="human-doc-1.xml"

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxkb2MgbGFuZz0iRU4tdXMi
Pg0KCTx0eXBlIG5hbWU9IkdyYXBoaWNzLlBvaW50IiBhc3NlbWJseT0iUG9pbnQiPg0KCQk8cmVt
YXJrcz5DbGFzcyA8Yz5Qb2ludDwvYz4gbW9kZWxzIGEgcG9pbnQgaW4gYSB0d28tZGltZW5zaW9u
YWwgcGxhbmUuPC9yZW1hcmtzPg0KCQkNCgkJPCEtLSBmaWVsZHMgLS0+DQoJCTxmaWVsZCBuYW1l
PSJ4Ij4NCgkJCTxzdW1tYXJ5Pkluc3RhbmNlIHZhcmlhYmxlIDxjPng8L2M+IHJlcHJlc2VudHMg
dGhlIHBvaW50J3MgeC1jb29yZGluYXRlLjwvc3VtbWFyeT4NCgkJPC9maWVsZD4NCgkJPGZpZWxk
IG5hbWU9InkiPg0KCQkJPHN1bW1hcnk+SW5zdGFuY2UgdmFyaWFibGUgPGM+eTwvYz4gcmVwcmVz
ZW50cyB0aGUgcG9pbnQncyB5LWNvb3JkaW5hdGUuPC9zdW1tYXJ5Pg0KCQk8L2ZpZWxkPg0KCQkN
CgkJPCEtLSBtZXRob2RzIC0tPg0KCQk8bWV0aG9kIG5hbWU9IiNjdG9yIj4NCgkJCTxzdW1tYXJ5
PlRoaXMgY29uc3RydWN0b3IgaW5pdGlhbGl6ZXMgdGhlIG5ldyBwb2ludCB0byAoMCwwKS48L3N1
bW1hcnk+DQoJCTwvbWV0aG9kPg0KCQkNCgkJPG1ldGhvZCBuYW1lPSIjY3RvcihTeXN0ZW0uSW50
MzIsU3lzdGVtLkludDMyKSI+DQoJCQk8c3VtbWFyeT5UaGlzIGNvbnN0cnVjdG9yIGluaXRpYWxp
emVzIHRoZSBuZXcgUG9pbnQgdG8gKDxwYXJhbXJlZiBuYW1lPSJ4b3IiIC8+LDxwYXJhbXJlZiBu
YW1lPSJ5b3IiIC8+KS48L3N1bW1hcnk+DQoJCQk8cGFyYW0+PGM+eG9yPC9jPiBpcyB0aGUgbmV3
IHgtY29vcmRpbmF0ZS48L3BhcmFtPg0KCQkJPHBhcmFtPjxjPnlvcjwvYz4gaXMgdGhlIG5ldyB5
LWNvb3JkaW5hdGUuPC9wYXJhbT4NCgkJPC9tZXRob2Q+DQoJCQ0KCQk8bWV0aG9kIG5hbWU9Ik1v
dmUoU3lzdGVtLkludDMyLFN5c3RlbS5JbnQzMikiPg0KCQkJPHN1bW1hcnk+VGhpcyBtZXRob2Qg
Y2hhbmdlcyB0aGUgcG9pbnQncyBsb2NhdGlvbiB0byB0aGUgZ2l2ZW4gY29vcmRpbmF0ZXMuPC9z
dW1tYXJ5Pg0KCQkJPHBhcmFtPjxjPnhvcjwvYz4gaXMgdGhlIG5ldyB4LWNvb3JkaW5hdGUuPC9w
YXJhbT4NCgkJCTxwYXJhbT48Yz55b3I8L2M+IGlzIHRoZSBuZXcgeS1jb29yZGluYXRlLjwvcGFy
YW0+DQoJCQk8c2VlIGNyZWY9IlRyYW5zbGF0ZShTeXN0ZW0uSW50MzIsU3lzdGVtLkludDMyKSIg
Lz4NCgkJPC9tZXRob2Q+DQoJCQ0KCQk8bWV0aG9kIG5hbWU9IlRyYW5zbGF0ZShTeXN0ZW0uSW50
MzIsU3lzdGVtLkludDMyKSI+DQoJCQk8c3VtbWFyeT5UaGlzIG1ldGhvZCBjaGFuZ2VzIHRoZSBw
b2ludCdzIGxvY2F0aW9uIGJ5IHRoZSBnaXZlbiB4LSBhbmQgeS1vZmZzZXRzLg0KCQkJCTxleGFt
cGxlIGxhbmc9IkMjIj4NCgkJCQkJQSBDIyBleGFtcGxlOg0KCQkJCQkJPGNvZGU+DQoJCQkJCQkJ
UG9pbnQgcCA9IG5ldyBQb2ludCgzLCA1KTsNCgkJCQkJCQlwLlRyYW5zbGF0ZSgtMSwgMyk7DQoJ
CQkJCQk8L2NvZGU+DQoJCQkJCVRoaXMgY29kZSByZXN1bHRzIGluIDxjPnA8L2M+IGhhdmluZyB0
aGUgdmFsdWUgKDIsOCkuDQoJCQkJPC9leGFtcGxlPg0KCQkJPC9zdW1tYXJ5Pg0KCQkJPHBhcmFt
PjxjPnhvcjwvYz4gaXMgdGhlIHJlbGF0aXZlIHgtb2Zmc2V0LjwvcGFyYW0+DQoJCQk8cGFyYW0+
PGM+eW9yPC9jPiBpcyB0aGUgcmVsYXRpdmUgeS1vZmZzZXQuPC9wYXJhbT4NCgkJCTxzZWUgY3Jl
Zj0iTW92ZShTeXN0ZW0uSW50MzIsU3lzdGVtLkludDMyKSIgLz4NCgkJPC9tZXRob2Q+DQoJCQ0K
CQk8bWV0aG9kIG5hbWU9IkVxdWFscyhTeXN0ZW0uT2JqZWN0KSI+DQoJCQk8c3VtbWFyeT5UaGlz
IG1ldGhvZCBkZXRlcm1pbmVzIHdoZXRoZXIgdHdvIHBvaW50cyBoYXZlIHRoZSBzYW1lIGxvY2F0
aW9uLjwvc3VtbWFyeT4NCgkJCTxwYXJhbT48Yz5vPC9jPiBpcyB0aGUgb2JqZWN0IHRvIGJlIGNv
bXBhcmVkIHRvIHRoZSBjdXJyZW50IG9iamVjdC48L3BhcmFtPg0KCQkJPHJldHVybnM+VHJ1ZSBp
ZiB0aGUgUG9pbnRzIGhhdmUgdGhlIHNhbWUgbG9jYXRpb24gYW5kIHRoZXkgaGF2ZSB0aGUgZXhh
Y3Qgc2FtZSB0eXBlOyBvdGhlcndpc2UsIGZhbHNlLjwvcmV0dXJucz4NCgkJCTxzZWVhbHNvIGNy
ZWY9Im9wX0VxdWFsaXR5KEdyYXBoaWNzLlBvaW50LEdyYXBoaWNzLlBvaW50KSIgLz4NCgkJCTxz
ZWVhbHNvIGNyZWY9Im9wX0luZXF1YWxpdHkoR3JhcGhpY3MuUG9pbnQsR3JhcGhpY3MuUG9pbnQi
IC8+DQoJCTwvbWV0aG9kPg0KCQkNCgkJPG1ldGhvZCBuYW1lPSJUb1N0cmluZyI+DQoJCQk8c3Vt
bWFyeT5SZXBvcnQgYSBwb2ludCdzIGxvY2F0aW9uIGFzIGEgc3RyaW5nLjwvc3VtbWFyeT4NCgkJ
CTxyZXR1cm5zPkEgc3RyaW5nIHJlcHJlc2VudGluZyBhIHBvaW50J3MgbG9jYXRpb24sIGluIHRo
ZSBmb3JtICh4LHkpLCB3aXRob3V0IGFueSBsZWFkaW5nLCB0cmFpbGluZywgb3IgZW1iZWRkZWQg
d2hpdGVzcGFjZS48L3JldHVybnM+DQoJCTwvbWV0aG9kPg0KCQkNCgkJPG1ldGhvZCBuYW1lPSJv
cF9FcXVhbGl0eShHcmFwaGljcy5Qb2ludCxHcmFwaGljcy5Qb2ludCkiPg0KCQkJPHN1bW1hcnk+
VGhpcyBvcGVyYXRvciBkZXRlcm1pbmVzIHdoZXRoZXIgdHdvIHBvaW50cyBoYXZlIHRoZSBzYW1l
IGxvY2F0aW9uLjwvc3VtbWFyeT4NCgkJCTxwYXJhbT48Yz5wMTwvYz4gaXMgdGhlIGZpcnN0IFBv
aW50IHRvIGJlIGNvbXBhcmVkLjwvcGFyYW0+DQoJCQk8cGFyYW0+PGM+cDI8L2M+IGlzIHRoZSBz
ZWNvbmQgUG9pbnQgdG8gYmUgY29tcGFyZWQuPC9wYXJhbT4NCgkJCTxyZXR1cm5zPlRydWUgaWYg
dGhlIHBvaW50cyBoYXZlIHRoZSBzYW1lIGxvY2F0aW9uIGFuZCB0aGV5IGhhdmUgdGhlIGV4YWN0
IHNhbWUgdHlwZTsgb3RoZXJ3aXNlLCBmYWxzZS48L3JldHVybnM+DQoJCQk8c2VlYWxzbyBjcmVm
PSJFcXVhbHMoU3lzdGVtLk9iamVjdCkiIC8+DQoJCQk8c2VlYWxzbyBjcmVmPSJvcF9JbmVxdWFs
aXR5KEdyYXBoaWNzLlBvaW50LEdyYXBoaWNzLlBvaW50KSIgLz4NCgkJPC9tZXRob2Q+DQoNCgkJ
PG1ldGhvZCBuYW1lPSJvcF9JbmVxdWFsaXR5KEdyYXBoaWNzLlBvaW50LEdyYXBoaWNzLlBvaW50
KSI+DQoJCQk8c3VtbWFyeT5UaGlzIG9wZXJhdG9yIGRldGVybWluZXMgd2hldGhlciB0d28gcG9p
bnRzIGhhdmUgdGhlIHNhbWUgbG9jYXRpb24uPC9zdW1tYXJ5Pg0KCQkJPHBhcmFtPjxjPnAxPC9j
PiBpcyB0aGUgZmlyc3QgUG9pbnQgdG8gYmUgY29tcGFyZWQuPC9wYXJhbT4NCgkJCTxwYXJhbT48
Yz5wMjwvYz4gaXMgdGhlIHNlY29uZCBQb2ludCB0byBiZSBjb21wYXJlZC48L3BhcmFtPg0KCQkJ
PHJldHVybnM+VHJ1ZSBpZiB0aGUgcG9pbnRzIGRvIG5vdCBoYXZlIHRoZSBzYW1lIGxvY2F0aW9u
IGFuZCB0aGV5IGhhdmUgdGhlIGV4YWN0IHNhbWUgdHlwZTsgb3RoZXJ3aXNlLCBmYWxzZS48L3Jl
dHVybnM+DQoJCQk8c2VlYWxzbyBjcmVmPSJFcXVhbHMoU3lzdGVtLk9iamVjdCkiIC8+DQoJCQk8
c2VlYWxzbyBjcmVmPSJvcF9FcXVhbGl0eShHcmFwaGljcy5Qb2ludCxHcmFwaGljcy5Qb2ludCki
IC8+DQoJCTwvbWV0aG9kPg0KCQkNCgkJPG1ldGhvZCBuYW1lPSJNYWluIj4NCgkJCTxzdW1tYXJ5
Pg0KCQkJCVRoaXMgaXMgdGhlIGVudHJ5IHBvaW50IG9mIHRoZSBQb2ludCBjbGFzcyB0ZXN0aW5n
IHByb2dyYW0uDQoJCQkJPHBhcmE+VGhpcyBwcm9ncmFtIHRlc3RzIGVhY2ggbWV0aG9kIGFuZCBv
cGVyYXRvciwgYW5kIGlzIGludGVuZGVkIHRvIGJlIHJ1biBhZnRlciBhbnkgbm9uLXRyaXZpYWwg
bWFpbnRlbmFuY2UgaGFzIGJlZW4gcGVyZm9ybWVkIG9uIHRoZSBQb2ludCBjbGFzcy48L3BhcmE+
DQoJCQk8L3N1bW1hcnk+DQoJCTwvbWV0aG9kPg0KCQkNCgkJPCEtLSBwcm9wZXJ0aWVzIC0tPg0K
CQk8cHJvcGVydHkgbmFtZT0iWCI+DQoJCQk8dmFsdWU+UHJvcGVydHkgPGM+WDwvYz4gcmVwcmVz
ZW50cyB0aGUgcG9pbnQncyB4LWNvb3JkaW5hdGUuPC92YWx1ZT4NCgkJPC9wcm9wZXJ0eT4NCgkJ
DQoJCTxwcm9wZXJ0eSBuYW1lPSJZIj4NCgkJCTx2YWx1ZT5Qcm9wZXJ0eSA8Yz55PC9jPiByZXBy
ZXNlbnRzIHRoZSBwb2ludCdzIHktY29vcmRpbmF0ZS48L3ZhbHVlPg0KCQk8L3Byb3BlcnR5Pg0K
CTwvdHlwZT4NCjwvZG9jPg0K
--=====================_63669311==_--