[haiku-doc] Re: Revert doxygen to version 1.7.6

  • From: Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx>
  • To: haiku-doc@xxxxxxxxxxxxx
  • Date: Sun, 23 Dec 2012 20:29:46 +0100


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 and the documentation has already been regenerated.
> Output looks good again on, 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?



Other related posts: