Re: [Xen-API] improving the XenAPI docs

[Jesse Benedict <jesse.benedict@xxxxxxxxxx>]

I really like the idea!

With regards to the grouping - I think I can help and attached is a file.  The 
"xe help --all" command groups all 417+ commands into their logical order.  
With each release, I have a simple Perl script that extracts this so I can 
inject it into a Word Document for sharing, knowledge, and my "aging brain".

With regards to the API, I would really like to see examples - based on the SDK 
and third-party code supported - to give an example of how each call could be 
used.  That may take some time, but would definitely be worth the effort in the 
long run.

Sincerely,


Jesse Benedict, CCSP, CCA | Sr. Technical Support (10:00 â 19:00 EST) | Citrix 
Systems, Inc. 


-----Original Message-----
From: xs-devel-request@xxxxxxxxxxxxxxxxxxx 
[mailto:xs-devel-request@xxxxxxxxxxxxxxxxxxx] On Behalf Of Dave Scott
Sent: Tuesday, January 27, 2015 4:03 PM
To: xen-api@xxxxxxxxxxxxxxxxxxxx
Cc: xs-devel
Subject: [xs-devel] improving the XenAPI docs

Hi,

Iâve been thinking about how to improve the XenAPI reference[1]. The things I 
like about the reference are:

- itâs generated from the IDL, so itâs always up to date
- itâs got everything in it

The things I donât like about the reference are:

- itâs got everything in itâ in alphabetical order, rather than in any kind of 
usefulness order
- the descriptions of fields/ functions areâ terse (and often tautologous)
- there are no in-line examples

Iâd like to improve the reference by making 2 extensions:

1. Iâd like to add tags to each field and function, and allow the docs to be 
searched by tag (e.g. find all the fields and functions related to âsnapshotsâ) 
A well-known tag name would be âcoreâ meaning âstuff you need to knowâ and I 
propose we either filter for that by default, or at least re-order the elements 
so we have core first.

2. Iâd like to create a sparse file overlay per-API in the xen-api repo. An 
overlay file â if it exists â would override whatever terse description exists 
in the raw IDL. The overlay would be written in markdown and would contain 
paragraphs of description, links and example usages. It would be easy to add an 
overlay to the repo without breaking the build (i.e. thereâs no need to keep 
all the docs inside the code as well-quoted strings where you have to satisfy 
the compiler).

Thoughts/ suggestions/ improvements welcome!

Cheers,
Dave

[1] Thereâs more than one copy on the web, but hereâs the one I was looking at: 
http://xapi-project.github.io/xen-api/index.html

Attachment: 6.5 COMMANDS
Description: 6.5 COMMANDS

_______________________________________________
Xen-api mailing list
Xen-api@xxxxxxxxxxxxx
http://lists.xen.org/cgi-bin/mailman/listinfo/xen-api