corinthia-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Peter Kelly <pmke...@apache.org>
Subject Re: Code explanations in Wiki ?
Date Tue, 12 May 2015 16:25:13 GMT
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
pmkelly@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 <jani@apache.org> wrote:
> 
> On 12 May 2015 at 17:39, Gabriela Gibson <gabriela.gibson@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 <jani@apache.org> wrote:
>>> On 12 May 2015 at 13:52, Gabriela Gibson <gabriela.gibson@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 <jani@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/
>> 


Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message