Re: Documentation HTML errors
- Posted by ne1uno Aug 24, 2009
- 880 views
It would still be nice to have exact errors in the bug system so they can be fixed by the time 4.0b3 is released. Most doc bugs are easily fixed and it's very possible to make the fix to the manual before 4.0b2.
The Euphoria manual has a number of routines and constants identified by 'Unknown'.
This has caused me to refer to the wrong section for one routine.
it's easy enough to find undocumented with grep if you have all the html in one place.
@echo grep for Undocumented >un.txt %grep% -n -l -c -i "Undocumented" eu4*.html >>un.txt %grep% -C3 -i "Undocumented" eu4*.html >>un.txt
there are some genuine undocumented functions. you would see the include file and a function signature followed by "undocumented". there are a few cases where one routine, constant or builtin is documented but through markup or eudoc error the next function becomes the function signature before the documented one. eudoc should probably make a page of any undocumented or unknown links as an option.
the goal of keeping the documentation with the code breaks down a little with the memory rountines and builtins because of SAFE. with eu4 you always only include std/machine.e
the commandline option -D SAFE or with define SAFE in a program will include memory.e or safe.e as required.
eudoc currently has no way to specify the include file or to exclude sections of comments, so the docs appear to suggest include std/memory.e or std/safe.e might be necessary. as well as presenting many more export and override routiines & constants to search through than anyone not maintaining euphoria itself would ever use. you also have something like peeks undocumented under safe.e while referenced as a builtin elsewhere.
it might be better to remove std/safe,e and std/memory,e from eudoc scanning. move all the documentation about builtins currently in std/machine.e to docs/memory.txt and present a simpler reference to what is available.
meantime, the fix for a few of the undocumeted were some excess blank lines. allocate_string was moveed around without also moving the matching doc comments. fix will be in the next beta and next online doc generation.
