mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2025-03-07 17:28:15 +00:00
Fix API doc extractor to stop munging comment formatting
The python method help docs are copied across from the C funtion comments, but in the process all line breaks and indentation was being lost. This made the resulting text and code examples completely unreadable. Both the API doc extractor and the python generator were destroying whitespace & this fixes them to preserve it exactly. * docs/apibuild.py: Preserve all whitespace when extracting function comments. Print function comment inside a <![CDATA[ section to fully preserve all whitespace. Look for the word 'returns' to describe return values, instead of 'return' to avoid getting confused with code examples including the C 'return' statement. * python/generator.py: Preserve all whitespace when printing function help docs * src/libvirt.c: Change any return parameter indicated by 'return' to be 'returns', to avoid confusing the API extractor * docs/libvirt-api.xml: Re-build for fixed descriptions
This commit is contained in:
parent
d104362d90
commit
5486abfe4e
@ -838,14 +838,20 @@ class CParser:
|
|||||||
arg, name))
|
arg, name))
|
||||||
while len(lines) > 0 and lines[0] == '*':
|
while len(lines) > 0 and lines[0] == '*':
|
||||||
del lines[0]
|
del lines[0]
|
||||||
desc = ""
|
desc = None
|
||||||
while len(lines) > 0:
|
while len(lines) > 0:
|
||||||
l = lines[0]
|
l = lines[0]
|
||||||
while len(l) > 0 and l[0] == '*':
|
i = 0
|
||||||
l = l[1:]
|
# Remove all leading '*', followed by at most one ' ' character
|
||||||
l = string.strip(l)
|
# since we need to preserve correct identation of code examples
|
||||||
if len(l) >= 6 and l[0:6] == "return" or l[0:6] == "Return":
|
while i < len(l) and l[i] == '*':
|
||||||
try:
|
i = i + 1
|
||||||
|
if i > 0:
|
||||||
|
if i < len(l) and l[i] == ' ':
|
||||||
|
i = i + 1
|
||||||
|
l = l[i:]
|
||||||
|
if len(l) >= 6 and l[0:7] == "returns" or l[0:7] == "Returns":
|
||||||
|
try:
|
||||||
l = string.split(l, ' ', 1)[1]
|
l = string.split(l, ' ', 1)[1]
|
||||||
except:
|
except:
|
||||||
l = ""
|
l = ""
|
||||||
@ -859,9 +865,14 @@ class CParser:
|
|||||||
retdesc = retdesc + " " + l
|
retdesc = retdesc + " " + l
|
||||||
del lines[0]
|
del lines[0]
|
||||||
else:
|
else:
|
||||||
desc = desc + " " + l
|
if desc is not None:
|
||||||
|
desc = desc + "\n" + l
|
||||||
|
else:
|
||||||
|
desc = l
|
||||||
del lines[0]
|
del lines[0]
|
||||||
|
|
||||||
|
if desc is None:
|
||||||
|
desc = ""
|
||||||
retdesc = string.strip(retdesc)
|
retdesc = string.strip(retdesc)
|
||||||
desc = string.strip(desc)
|
desc = string.strip(desc)
|
||||||
|
|
||||||
@ -1716,7 +1727,7 @@ class docBuilder:
|
|||||||
try:
|
try:
|
||||||
(args, desc) = id.info
|
(args, desc) = id.info
|
||||||
if desc != None and desc != "":
|
if desc != None and desc != "":
|
||||||
output.write(" <info>%s</info>\n" % (escape(desc)))
|
output.write(" <info><![CDATA[%s]]></info>\n" % (desc))
|
||||||
self.indexString(name, desc)
|
self.indexString(name, desc)
|
||||||
for arg in args:
|
for arg in args:
|
||||||
(name, desc) = arg
|
(name, desc) = arg
|
||||||
@ -1760,7 +1771,7 @@ class docBuilder:
|
|||||||
try:
|
try:
|
||||||
desc = id.extra
|
desc = id.extra
|
||||||
if desc != None and desc != "":
|
if desc != None and desc != "":
|
||||||
output.write(">\n <info>%s</info>\n" % (escape(desc)))
|
output.write(">\n <info><![CDATA[%s]]></info>\n" % (desc))
|
||||||
output.write(" </typedef>\n")
|
output.write(" </typedef>\n")
|
||||||
else:
|
else:
|
||||||
output.write("/>\n")
|
output.write("/>\n")
|
||||||
@ -1796,7 +1807,7 @@ class docBuilder:
|
|||||||
output.write(" <cond>%s</cond>\n"% (apstr));
|
output.write(" <cond>%s</cond>\n"% (apstr));
|
||||||
try:
|
try:
|
||||||
(ret, params, desc) = id.info
|
(ret, params, desc) = id.info
|
||||||
output.write(" <info>%s</info>\n" % (escape(desc)))
|
output.write(" <info><![CDATA[%s]]></info>\n" % (desc))
|
||||||
self.indexString(name, desc)
|
self.indexString(name, desc)
|
||||||
if ret[0] != None:
|
if ret[0] != None:
|
||||||
if ret[0] == "void":
|
if ret[0] == "void":
|
||||||
|
File diff suppressed because it is too large
Load Diff
@ -44,6 +44,7 @@ if sgmlop:
|
|||||||
self.finish_starttag = target.start
|
self.finish_starttag = target.start
|
||||||
self.finish_endtag = target.end
|
self.finish_endtag = target.end
|
||||||
self.handle_data = target.data
|
self.handle_data = target.data
|
||||||
|
self.handle_cdata = target.cdata
|
||||||
|
|
||||||
# activate parser
|
# activate parser
|
||||||
self.parser = sgmlop.XMLParser()
|
self.parser = sgmlop.XMLParser()
|
||||||
@ -78,6 +79,7 @@ class SlowParser(xmllib.XMLParser):
|
|||||||
def __init__(self, target):
|
def __init__(self, target):
|
||||||
self.unknown_starttag = target.start
|
self.unknown_starttag = target.start
|
||||||
self.handle_data = target.data
|
self.handle_data = target.data
|
||||||
|
self.handle_cdata = target.cdata
|
||||||
self.unknown_endtag = target.end
|
self.unknown_endtag = target.end
|
||||||
xmllib.XMLParser.__init__(self)
|
xmllib.XMLParser.__init__(self)
|
||||||
|
|
||||||
@ -108,6 +110,11 @@ class docParser:
|
|||||||
print "data %s" % text
|
print "data %s" % text
|
||||||
self._data.append(text)
|
self._data.append(text)
|
||||||
|
|
||||||
|
def cdata(self, text):
|
||||||
|
if debug:
|
||||||
|
print "data %s" % text
|
||||||
|
self._data.append(text)
|
||||||
|
|
||||||
def start(self, tag, attrs):
|
def start(self, tag, attrs):
|
||||||
if debug:
|
if debug:
|
||||||
print "start %s, %s" % (tag, attrs)
|
print "start %s, %s" % (tag, attrs)
|
||||||
@ -843,20 +850,14 @@ def writeDoc(name, args, indent, output):
|
|||||||
val = string.replace(val, "NULL", "None");
|
val = string.replace(val, "NULL", "None");
|
||||||
output.write(indent)
|
output.write(indent)
|
||||||
output.write('"""')
|
output.write('"""')
|
||||||
while len(val) > 60:
|
i = string.find(val, "\n")
|
||||||
if val[0] == " ":
|
while i >= 0:
|
||||||
val = val[1:]
|
str = val[0:i+1]
|
||||||
continue
|
val = val[i+1:]
|
||||||
str = val[0:60]
|
|
||||||
i = string.rfind(str, " ");
|
|
||||||
if i < 0:
|
|
||||||
i = 60
|
|
||||||
str = val[0:i]
|
|
||||||
val = val[i:]
|
|
||||||
output.write(str)
|
output.write(str)
|
||||||
output.write('\n ');
|
i = string.find(val, "\n")
|
||||||
output.write(indent)
|
output.write(indent)
|
||||||
output.write(val);
|
output.write(val)
|
||||||
output.write(' """\n')
|
output.write(' """\n')
|
||||||
|
|
||||||
def buildWrappers():
|
def buildWrappers():
|
||||||
|
@ -814,7 +814,7 @@ virRegisterStateDriver(virStateDriverPtr driver)
|
|||||||
*
|
*
|
||||||
* Initialize all virtualization drivers.
|
* Initialize all virtualization drivers.
|
||||||
*
|
*
|
||||||
* Return 0 if all succeed, -1 upon any failure.
|
* Returns 0 if all succeed, -1 upon any failure.
|
||||||
*/
|
*/
|
||||||
int virStateInitialize(int privileged) {
|
int virStateInitialize(int privileged) {
|
||||||
int i, ret = 0;
|
int i, ret = 0;
|
||||||
@ -835,7 +835,7 @@ int virStateInitialize(int privileged) {
|
|||||||
*
|
*
|
||||||
* Run each virtualization driver's cleanup method.
|
* Run each virtualization driver's cleanup method.
|
||||||
*
|
*
|
||||||
* Return 0 if all succeed, -1 upon any failure.
|
* Returns 0 if all succeed, -1 upon any failure.
|
||||||
*/
|
*/
|
||||||
int virStateCleanup(void) {
|
int virStateCleanup(void) {
|
||||||
int i, ret = 0;
|
int i, ret = 0;
|
||||||
@ -853,7 +853,7 @@ int virStateCleanup(void) {
|
|||||||
*
|
*
|
||||||
* Run each virtualization driver's reload method.
|
* Run each virtualization driver's reload method.
|
||||||
*
|
*
|
||||||
* Return 0 if all succeed, -1 upon any failure.
|
* Returns 0 if all succeed, -1 upon any failure.
|
||||||
*/
|
*/
|
||||||
int virStateReload(void) {
|
int virStateReload(void) {
|
||||||
int i, ret = 0;
|
int i, ret = 0;
|
||||||
@ -871,7 +871,7 @@ int virStateReload(void) {
|
|||||||
*
|
*
|
||||||
* Run each virtualization driver's "active" method.
|
* Run each virtualization driver's "active" method.
|
||||||
*
|
*
|
||||||
* Return 0 if none are active, 1 if at least one is.
|
* Returns 0 if none are active, 1 if at least one is.
|
||||||
*/
|
*/
|
||||||
int virStateActive(void) {
|
int virStateActive(void) {
|
||||||
int i, ret = 0;
|
int i, ret = 0;
|
||||||
@ -7040,7 +7040,7 @@ virStoragePoolRef(virStoragePoolPtr pool)
|
|||||||
* involve communicating with a remote server, and/or initializing
|
* involve communicating with a remote server, and/or initializing
|
||||||
* new devices at the OS layer
|
* new devices at the OS layer
|
||||||
*
|
*
|
||||||
* Return 0 if the volume list was refreshed, -1 on failure
|
* Returns 0 if the volume list was refreshed, -1 on failure
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
virStoragePoolRefresh(virStoragePoolPtr pool,
|
virStoragePoolRefresh(virStoragePoolPtr pool,
|
||||||
@ -7085,7 +7085,7 @@ error:
|
|||||||
*
|
*
|
||||||
* Fetch the locally unique name of the storage pool
|
* Fetch the locally unique name of the storage pool
|
||||||
*
|
*
|
||||||
* Return the name of the pool, or NULL on error
|
* Returns the name of the pool, or NULL on error
|
||||||
*/
|
*/
|
||||||
const char*
|
const char*
|
||||||
virStoragePoolGetName(virStoragePoolPtr pool)
|
virStoragePoolGetName(virStoragePoolPtr pool)
|
||||||
@ -7109,7 +7109,7 @@ virStoragePoolGetName(virStoragePoolPtr pool)
|
|||||||
*
|
*
|
||||||
* Fetch the globally unique ID of the storage pool
|
* Fetch the globally unique ID of the storage pool
|
||||||
*
|
*
|
||||||
* Return 0 on success, or -1 on error;
|
* Returns 0 on success, or -1 on error;
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
virStoragePoolGetUUID(virStoragePoolPtr pool,
|
virStoragePoolGetUUID(virStoragePoolPtr pool,
|
||||||
@ -7145,7 +7145,7 @@ error:
|
|||||||
*
|
*
|
||||||
* Fetch the globally unique ID of the storage pool as a string
|
* Fetch the globally unique ID of the storage pool as a string
|
||||||
*
|
*
|
||||||
* Return 0 on success, or -1 on error;
|
* Returns 0 on success, or -1 on error;
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
virStoragePoolGetUUIDString(virStoragePoolPtr pool,
|
virStoragePoolGetUUIDString(virStoragePoolPtr pool,
|
||||||
@ -7186,7 +7186,7 @@ error:
|
|||||||
* Get volatile information about the storage pool
|
* Get volatile information about the storage pool
|
||||||
* such as free space / usage summary
|
* such as free space / usage summary
|
||||||
*
|
*
|
||||||
* returns 0 on success, or -1 on failure.
|
* Returns 0 on success, or -1 on failure.
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
virStoragePoolGetInfo(virStoragePoolPtr pool,
|
virStoragePoolGetInfo(virStoragePoolPtr pool,
|
||||||
@ -7236,7 +7236,7 @@ error:
|
|||||||
* storage pool. This is suitable for later feeding back
|
* storage pool. This is suitable for later feeding back
|
||||||
* into the virStoragePoolCreateXML method.
|
* into the virStoragePoolCreateXML method.
|
||||||
*
|
*
|
||||||
* returns a XML document, or NULL on error
|
* Returns a XML document, or NULL on error
|
||||||
*/
|
*/
|
||||||
char *
|
char *
|
||||||
virStoragePoolGetXMLDesc(virStoragePoolPtr pool,
|
virStoragePoolGetXMLDesc(virStoragePoolPtr pool,
|
||||||
@ -7283,7 +7283,7 @@ error:
|
|||||||
* Fetches the value of the autostart flag, which determines
|
* Fetches the value of the autostart flag, which determines
|
||||||
* whether the pool is automatically started at boot time
|
* whether the pool is automatically started at boot time
|
||||||
*
|
*
|
||||||
* return 0 on success, -1 on failure
|
* Returns 0 on success, -1 on failure
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
virStoragePoolGetAutostart(virStoragePoolPtr pool,
|
virStoragePoolGetAutostart(virStoragePoolPtr pool,
|
||||||
@ -7329,7 +7329,7 @@ error:
|
|||||||
*
|
*
|
||||||
* Sets the autostart flag
|
* Sets the autostart flag
|
||||||
*
|
*
|
||||||
* returns 0 on success, -1 on failure
|
* Returns 0 on success, -1 on failure
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
virStoragePoolSetAutostart(virStoragePoolPtr pool,
|
virStoragePoolSetAutostart(virStoragePoolPtr pool,
|
||||||
@ -7490,7 +7490,7 @@ virStorageVolGetConnect (virStorageVolPtr vol)
|
|||||||
* Fetch a pointer to a storage volume based on its name
|
* Fetch a pointer to a storage volume based on its name
|
||||||
* within a pool
|
* within a pool
|
||||||
*
|
*
|
||||||
* return a storage volume, or NULL if not found / error
|
* Returns a storage volume, or NULL if not found / error
|
||||||
*/
|
*/
|
||||||
virStorageVolPtr
|
virStorageVolPtr
|
||||||
virStorageVolLookupByName(virStoragePoolPtr pool,
|
virStorageVolLookupByName(virStoragePoolPtr pool,
|
||||||
@ -7535,7 +7535,7 @@ error:
|
|||||||
* Fetch a pointer to a storage volume based on its
|
* Fetch a pointer to a storage volume based on its
|
||||||
* globally unique key
|
* globally unique key
|
||||||
*
|
*
|
||||||
* return a storage volume, or NULL if not found / error
|
* Returns a storage volume, or NULL if not found / error
|
||||||
*/
|
*/
|
||||||
virStorageVolPtr
|
virStorageVolPtr
|
||||||
virStorageVolLookupByKey(virConnectPtr conn,
|
virStorageVolLookupByKey(virConnectPtr conn,
|
||||||
@ -7578,7 +7578,7 @@ error:
|
|||||||
* Fetch a pointer to a storage volume based on its
|
* Fetch a pointer to a storage volume based on its
|
||||||
* locally (host) unique path
|
* locally (host) unique path
|
||||||
*
|
*
|
||||||
* return a storage volume, or NULL if not found / error
|
* Returns a storage volume, or NULL if not found / error
|
||||||
*/
|
*/
|
||||||
virStorageVolPtr
|
virStorageVolPtr
|
||||||
virStorageVolLookupByPath(virConnectPtr conn,
|
virStorageVolLookupByPath(virConnectPtr conn,
|
||||||
@ -7621,7 +7621,7 @@ error:
|
|||||||
* Fetch the storage volume name. This is unique
|
* Fetch the storage volume name. This is unique
|
||||||
* within the scope of a pool
|
* within the scope of a pool
|
||||||
*
|
*
|
||||||
* return the volume name, or NULL on error
|
* Returns the volume name, or NULL on error
|
||||||
*/
|
*/
|
||||||
const char*
|
const char*
|
||||||
virStorageVolGetName(virStorageVolPtr vol)
|
virStorageVolGetName(virStorageVolPtr vol)
|
||||||
@ -7646,7 +7646,7 @@ virStorageVolGetName(virStorageVolPtr vol)
|
|||||||
* unique, so the same volume will have the same
|
* unique, so the same volume will have the same
|
||||||
* key no matter what host it is accessed from
|
* key no matter what host it is accessed from
|
||||||
*
|
*
|
||||||
* return the volume key, or NULL on error
|
* Returns the volume key, or NULL on error
|
||||||
*/
|
*/
|
||||||
const char*
|
const char*
|
||||||
virStorageVolGetKey(virStorageVolPtr vol)
|
virStorageVolGetKey(virStorageVolPtr vol)
|
||||||
@ -7673,7 +7673,7 @@ virStorageVolGetKey(virStorageVolPtr vol)
|
|||||||
* on an XML description. Not all pools support
|
* on an XML description. Not all pools support
|
||||||
* creation of volumes
|
* creation of volumes
|
||||||
*
|
*
|
||||||
* return the storage volume, or NULL on error
|
* Returns the storage volume, or NULL on error
|
||||||
*/
|
*/
|
||||||
virStorageVolPtr
|
virStorageVolPtr
|
||||||
virStorageVolCreateXML(virStoragePoolPtr pool,
|
virStorageVolCreateXML(virStoragePoolPtr pool,
|
||||||
@ -7723,7 +7723,7 @@ error:
|
|||||||
* volume (name, perms) are passed via a typical volume
|
* volume (name, perms) are passed via a typical volume
|
||||||
* XML description.
|
* XML description.
|
||||||
*
|
*
|
||||||
* return the storage volume, or NULL on error
|
* Returns the storage volume, or NULL on error
|
||||||
*/
|
*/
|
||||||
virStorageVolPtr
|
virStorageVolPtr
|
||||||
virStorageVolCreateXMLFrom(virStoragePoolPtr pool,
|
virStorageVolCreateXMLFrom(virStoragePoolPtr pool,
|
||||||
@ -7777,7 +7777,7 @@ error:
|
|||||||
*
|
*
|
||||||
* Delete the storage volume from the pool
|
* Delete the storage volume from the pool
|
||||||
*
|
*
|
||||||
* Return 0 on success, or -1 on error
|
* Returns 0 on success, or -1 on error
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
virStorageVolDelete(virStorageVolPtr vol,
|
virStorageVolDelete(virStorageVolPtr vol,
|
||||||
@ -7823,7 +7823,7 @@ error:
|
|||||||
* Release the storage volume handle. The underlying
|
* Release the storage volume handle. The underlying
|
||||||
* storage volume continues to exist.
|
* storage volume continues to exist.
|
||||||
*
|
*
|
||||||
* Return 0 on success, or -1 on error
|
* Returns 0 on success, or -1 on error
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
virStorageVolFree(virStorageVolPtr vol)
|
virStorageVolFree(virStorageVolPtr vol)
|
||||||
@ -7881,7 +7881,7 @@ virStorageVolRef(virStorageVolPtr vol)
|
|||||||
* Fetches volatile information about the storage
|
* Fetches volatile information about the storage
|
||||||
* volume such as its current allocation
|
* volume such as its current allocation
|
||||||
*
|
*
|
||||||
* Return 0 on success, or -1 on failure
|
* Returns 0 on success, or -1 on failure
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
virStorageVolGetInfo(virStorageVolPtr vol,
|
virStorageVolGetInfo(virStorageVolPtr vol,
|
||||||
@ -7930,7 +7930,7 @@ error:
|
|||||||
* Fetch an XML document describing all aspects of
|
* Fetch an XML document describing all aspects of
|
||||||
* the storage volume
|
* the storage volume
|
||||||
*
|
*
|
||||||
* Return the XML document, or NULL on error
|
* Returns the XML document, or NULL on error
|
||||||
*/
|
*/
|
||||||
char *
|
char *
|
||||||
virStorageVolGetXMLDesc(virStorageVolPtr vol,
|
virStorageVolGetXMLDesc(virStorageVolPtr vol,
|
||||||
@ -8161,7 +8161,7 @@ error:
|
|||||||
* Fetch an XML document describing all aspects of
|
* Fetch an XML document describing all aspects of
|
||||||
* the device.
|
* the device.
|
||||||
*
|
*
|
||||||
* Return the XML document, or NULL on error
|
* Returns the XML document, or NULL on error
|
||||||
*/
|
*/
|
||||||
char *virNodeDeviceGetXMLDesc(virNodeDevicePtr dev, unsigned int flags)
|
char *virNodeDeviceGetXMLDesc(virNodeDevicePtr dev, unsigned int flags)
|
||||||
{
|
{
|
||||||
@ -9377,7 +9377,7 @@ virSecretRef(virSecretPtr secret)
|
|||||||
*
|
*
|
||||||
* Release the secret handle. The underlying secret continues to exist.
|
* Release the secret handle. The underlying secret continues to exist.
|
||||||
*
|
*
|
||||||
* Return 0 on success, or -1 on error
|
* Returns 0 on success, or -1 on error
|
||||||
*/
|
*/
|
||||||
int
|
int
|
||||||
virSecretFree(virSecretPtr secret)
|
virSecretFree(virSecretPtr secret)
|
||||||
|
Loading…
x
Reference in New Issue
Block a user