Hello everyone, (cc Simon Glass)
I just tried to make the documentation for uboot with the following command (checked out latest mainline sources);
make htmldocs
cc tools/kernel-doc/docproc.c -o tools/kernel-doc/docproc make U_BOOT_VERSION=2014.01-rc1 -C doc/DocBook/ htmldocs make[1]: Entering directory `/home/abraham/SPACE/docs_uboot/doc/DocBook' xmlto html -m /home/abraham/SPACE/docs_uboot/doc/DocBook/stylesheet.xsl --skip-validation -o /home/abraham/SPACE/docs_uboot/doc/DocBook/fs /home/abraham/SPACE/docs_uboot/doc/DocBook/fs.xml && echo '<a HREF="fs/index.html"> fs</a><p>' > /home/abraham/SPACE/docs_uboot/doc/DocBook/fs.html Input file /home/abraham/SPACE/docs_uboot/doc/DocBook/fs.xml not found make[1]: *** [/home/abraham/SPACE/docs_uboot/doc/DocBook/fs.html] Error 1 make[1]: Leaving directory `/home/abraham/SPACE/docs_uboot/doc/DocBook' make: *** [htmldocs] Error 2
The logs in doc/Docbook/Makefile indicate that it was Simon's commit which is causing this problem (at least, he's the one who added in the fs.xml dependency without committing said file). But even if I remove this from the Makefile;
make htmldocs
make U_BOOT_VERSION=2014.01-rc1 -C doc/DocBook/ htmldocs make[1]: Entering directory `/home/abraham/SPACE/docs_uboot/doc/DocBook' /home/abraham/SPACE/docs_uboot/tools/kernel-doc/docproc doc /home/abraham/SPACE/docs_uboot/doc/DocBook/linker_lists.tmpl
/home/abraham/SPACE/docs_uboot/doc/DocBook/linker_lists.xml
Error(/home/abraham/SPACE/docs_uboot/include/linker_lists.h:101): cannot understand prototype: '__LINKER_LISTS_H__ ' Error(/home/abraham/SPACE/docs_uboot/include/linker_lists.h:165): cannot understand prototype: '/** * ll_entry_start() - Point to first entry of linker-generated array * @_type: Data type of the entry * @_list: Name of the list in which this entry is placed * * This function returns (_type *) pointer to the very first entry of a * linker-generated array placed into subsection of .u_boot_list section * specified by _list argument. * * Since this macro defines an array start symbol, its leftmost index * must be 2 and its rightmost index must be 1. * * Example: * struct my_sub_cmd *msc = ll_entry_start(struct my_sub_cmd, cmd_sub); ' make[1]: *** [/home/abraham/SPACE/docs_uboot/doc/DocBook/linker_lists.xml] Error 2 make[1]: Leaving directory `/home/abraham/SPACE/docs_uboot/doc/DocBook' make: *** [htmldocs] Error 2
We can see that there's some issue with parsing the comments in the linker_lists.h header file.
I can understand general developer reluctance at updating documentation (I'm lazy about it too), but do we have any way to generate some kind of documentation for u-boot? Even Linux-style man pages will do.
Or is my only recourse to just refer all the doc/README.* files one at a time?
-Abraham Varricatt