I Added a Doxygen page to the wiki, with a couple of links to Doxygen and the salient page in the manual.
Added some space for Corinitha specific style rules and a todo list for improving this page. G On 5/12/15, jan i <j...@apache.org> wrote: > Hi. > > > Doxygen is a favorite of mine, it does what I like (most of the time). > > We do need some guidelines in the wiki, with examples, how/what to > document, but apart from that, just go ahead. > > rgds > jan I. > > > On 12 May 2015 at 18:43, Gabriela Gibson <gabriela.gib...@gmail.com> wrote: > >> Hi Peter, >> >> this is funny --- I DID confuse DocBook and Doxygen. I _meant_ >> Doxygen, I used it before, but for some reason I researched DocBook >> instead and it stuck. So much for brand recognition. >> >> I nearly learned to set up the wrong thing there %-) >> >> G >> >> On 5/12/15, Peter Kelly <pmke...@apache.org> wrote: >> > I would suggest we stick with doxygen for in-code documentation, which >> > is >> > what is already used in the (few) parts of the codebase that do have >> > API >> > documentation. >> > >> > — >> > Dr Peter M. Kelly >> > pmke...@apache.org >> > >> > PGP key: http://www.kellypmk.net/pgp-key < >> http://www.kellypmk.net/pgp-key> >> > (fingerprint 5435 6718 59F0 DD1F BFA0 5E46 2523 BAA1 44AE 2966) >> > >> >> On 12 May 2015, at 10:43 pm, jan i <j...@apache.org> wrote: >> >> >> >> On 12 May 2015 at 17:39, Gabriela Gibson <gabriela.gib...@gmail.com> >> >> wrote: >> >> >> >>> Hi Jan, >> >>> >> >>> I've been writing a toy "queueAPI" that is built with cmake, and it >> >>> just so happens that setting up and adding DocBook services is the >> >>> next job on that project list. >> >>> >> >>> I think that should make a nice demo case. >> >>> >> >> +1 It does not need to be a perfect demo, just so that we can >> >> understand >> >> the flow, and where the information is kept. >> >> >> >> rgds >> >> jan I. >> >> >> >> >> >>> >> >>> G >> >>> >> >>> >> >>> On 5/12/15, jan i <j...@apache.org> wrote: >> >>>> On 12 May 2015 at 13:52, Gabriela Gibson <gabriela.gib...@gmail.com> >> >>> wrote: >> >>>> >> >>>>> Hi Peter, >> >>>>> >> >>>>> thanks for all the explanations :-) >> >>>>> >> >>>>> Further to Jan's suggestion, I think that the DF* library functions >> >>>>> could benefit from DocBook comments, and be treated like an >> >>>>> internal >> >>>>> API. >> >>>>> >> >>>>> Whilst this is not for consumption for Corinthia users, it will be >> >>>>> useful for devs in general and help to flatten the learning curve >> >>>>> for >> >>>>> newbies initially, and it's nice to just check on the generated >> >>>>> HTML >> >>>>> page to quickly find the correct tool or see easily if a better >> method >> >>>>> is available. >> >>>>> >> >>>>> I wouldn't mind writing the initial cut thereof and it would help >> >>>>> me >> >>>>> understand the DF library better too. >> >>>>> >> >>>> I am not against the idea, just have a few comments: >> >>>> - If DocBook is maintained outside the source (header file) itself, >> >>>> I >> >>> would >> >>>> never trust it. It is ok if it is extracted from the source file >> >>>> - Dorte/I can make a subdir on our web for such documentation >> >>>> (divide >> >>>> in >> >>>> internal/external/editor) >> >>>> >> >>>> >> >>>> I never used DocBook, but different systems, could you please use a >> few >> >>>> words/examples of the workflow, and how we integrate it >> >>>> in the build process. >> >>>> >> >>>> thanks >> >>>> jan I. >> >>>> >> >>>> >> >>>>> G >> >>>>> >> >>>>> On 5/12/15, jan i <j...@apache.org> wrote: >> >>>>>> Hi Peter. >> >>>>>> >> >>>>>> Thanks for these super explanations, even though I work on the >> >>>>>> libraries >> >>>>> at >> >>>>>> the moment, they >> >>>>>> were very interesting to read. >> >>>>>> >> >>>>>> Should these mails (in a slightly modified form) go into our Wiki, >> >>>>>> maybe >> >>>>> as >> >>>>>> group "Thoughts >> >>>>>> around the codebase" or something similar ? >> >>>>>> >> >>>>>> Keep up the fun >> >>>>>> rgds >> >>>>>> jan I. >> >>>>>> >> >>>>> >> >>>>> >> >>>>> -- >> >>>>> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/ >> >>>>> >> >>>> >> >>> >> >>> >> >>> -- >> >>> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/ >> >>> >> > >> > >> >> >> -- >> Visit my Coding Diary: http://gabriela-gibson.blogspot.com/ >> > -- Visit my Coding Diary: http://gabriela-gibson.blogspot.com/
