Review: Needs Fixing

I have managed to create the documentation and the generation is very quick 
(even after you add all the functionality I still think it will be quicker than 
the old one).

I would have some remarks though:

1) the menu on the left in the modules.html page is broken:
here is what I get:
[...]
excel
excel
excel
excel
excel
excel
excel
excel
excel
excel

All 'excel' links point to the 
http://www.zorba-xquery.com/modules/excel/text
module documentation.
Both cryptography links point to 
http://www.zorba-xquery.com/modules/cryptography/hmac
and so on.


2) there is no page with all the functions that helps the user find a function 
by name
(please see function_index.html)


3) in the 'Namespaces' section: please make the namespaces links to the module 
documentation where this is possible
(for instance http://expath.org/ns/file should be a link to the EXPath Zorba 
module documentation)


4.1) in the 'Function Summary' please put back the hover text such that people 
know what is the connection between the pictures and function annotations
('S' means sequential, 'E' external and so on)


4.2) Also the pictures should be links pointing to the specs: for instance 
'external' should point to http://www.w3.org/TR/xquery-30/#dt-external-function 
and so on.
That is because not all the annotations come from W3C, there are also Zorba 
ones like 'scripting' that has to point to doc/zorba/html/scripting_spec.html.


4.3) put back the pictures in the function description. Example:
instead of 
append-binary#2
E S append-binary#2


5.1) there is no link to the actual XQuery module with a nice XQuery 
highlighting
This does not help for the external functions but it shows the actual 
implementation for the XQuery functions.


5.2) there is no links to the schemas with a nice XML highlighting


6) there are no examples


7.1) there is a bug in the 'Errors' section:
Please see for example append-binary#2:

Errors
    file:FOFL0004 If
    $file
    points to a directory.
    file:FOFL9999 If any other error occurs.

Instead of:
Errors
    file:FOFL0004 If <strong>$file</strong> points to a directory.
    file:FOFL9999 If any other error occurs.


7.2) same error is in the description of each function:
Please see append#3 function description.


8.1) the links to the Zorba documentation are broken.
See for instance http://www.zorba-xquery.com/modules/fetch and in the module 
description the link to the URI resolvers points to:
html/uriresolvers.html
instead of:
zorba/html/uriresolvers.html


8.2) the links to the FLWOR Foundation site and Apache from the bottom of the 
pages point to nowhere.
I'm reffering to the part:  
Zorba is supported by the FLWOR Foundation and distributed under Apache 
Licence, Version 2.0.


8.3) please run the web-crawler that checks there are no broken links in the 
generated documentation
-- 
https://code.launchpad.net/~zorba-coders/zorba/new-xqdoc/+merge/127663
Your team Zorba Coders is subscribed to branch lp:zorba.

-- 
Mailing list: https://launchpad.net/~zorba-coders
Post to     : zorba-coders@lists.launchpad.net
Unsubscribe : https://launchpad.net/~zorba-coders
More help   : https://help.launchpad.net/ListHelp

Reply via email to