On Sun, Dec 23, 2012 at 2:29 PM, Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx> wrote: > Hi, > > On Sun, Dec 23, 2012 at 6:17 PM, John Scipione <jscipione@xxxxxxxxx> wrote: >> On Sun, Dec 23, 2012 at 5:25 AM, Niels Sascha Reedijk >> <niels.reedijk@xxxxxxxxx> wrote: >>> Hi, >>> >>> On Sat, Dec 22, 2012 at 11:15 PM, John Scipione <jscipione@xxxxxxxxx> wrote: >>>> On Sat, Dec 22, 2012 at 4:35 PM, Niels Sascha Reedijk >>>> <niels.reedijk@xxxxxxxxx> wrote: >>>>>> Given that the documentation is broken on 1.8.1 installed on the >>>>>> server right now can we revert to 1.7.6 for the time being? We can >>>>>> update the code to look good and then update to the 1.8.x branch again >>>>>> later on. >>>>> >>>>> Yes, or not. I still want to see whether switching to the wiki >>>>> approach will work. I am sort of stuck on finding a roadmap right now. >>>>> I would also like to think about how we approach things like >>>>> organizing functions and creating navigation. >>>> >>>> I also think that is a good approach, at least I'm not in love with >>>> Doxygen. Problem is that Doxygen seems to be the best program out >>>> there for source code documentation. The wiki would be a good >>>> secondary solution though. We'd lose all the code checking that >>>> doxygen does, but the barrier to entry of fixing the docs would be >>>> lowered. If we could get a few more people involved in documentation >>>> writing it would be a net win. >>> >>> Actually, the checking with the header field would not be lost. The >>> wiki pages can be cross-checked with the Doxygen output and then it is >>> possible to find out which changes are there. >> >> I don't understand this, Doxygen doesn't produce very parseable >> warning output so it would be tough to use this to do checking on the >> wiki page. Are you referring to the generated documentation output? >> Even then I fail to see how you could cross-check the the doxygen >> output. Perhaps if you were to read the XML you could check that way. > > Re-parse the wiki page. Compare to the parsed XML. The current > skeletons on dev.haiku-os.org are also generated from the XML. That > should make it possible to see the differences between the members of > the header file and the actual documentation. > >>>>> Will we use header files as package containers (which is not really a >>>>> C++ convention, nor a Haiku one), or will we just use a liberal way of >>>>> organizing it? Like putting all the support kit functions on one page? >>>> >>>> I would organize classes by kit that seems to be the most reasonable >>>> way to organize them. >>> >>> So what do we do with functions, defines, enums, typedefs and what >>> else that are there? Organize by topic (like the BeBook does it) or >>> organize by header file (like Doxygen). >> >> I guess organize by header would be the way to go. I'd have to think >> about it some more. >> >>>>> Anyway, I will try to downgrade the server to 1.7.6. >>>> >>>> Okay, that will be helpful in the interim, at least the >>>> api.haiku-os.org page will look decent again. >>> >>> It is back at 188.8.131.52 and the documentation has already been regenerated. >> >> Output looks good again on 184.108.40.206, but, it doesn't seem to be pulling >> in my latest documentation changes. Missing BFile, BCursor, etc. > > Yes I see, it looks like the script is not updating the git > repository. I updated the script now. Did it work? Doesn't appear to have worked no, I guess we need to wait for a cron job to update the git repository on the server?