[LTP] LTP API documentation

[LTP] LTP API documentation

[Tim Bird]

Hey LTP developers,

Where is the API documentation, for stuff like tst_* and SAFE_*
and 'struct tst_test'

I looked in ltp/docs and on the wiki, but couldn't seem to find it.

I'm including a quick introduction to LTP in a talk I'm giving at ELC
next week, and would like to refer people to the API docs.

Thanks,
 -- Tim Bird
Senior Staff Software Engineer, Sony Corporation
Architecture Group Chair, Core Embedded Linux Project, Linux Foundation

[LTP] LTP API documentation

[Cyril Hrubis]

Hi!
> Where is the API documentation, for stuff like tst_* and SAFE_*
> and 'struct tst_test'
> 
> I looked in ltp/docs and on the wiki, but couldn't seem to find it.

It's named test-writing-guidelines, which arguably is a bit confusing
but its there:

ltp/doc/test-writing-guidelines.txt or
https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines

And we also have nice C testcase tutorial:

doc/c-test-tutorial-simple.txt or
https://github.com/linux-test-project/ltp/wiki/C-Test-Case-Tutorial

-- 
Cyril Hrubis
chrubis@suse.cz

[LTP] LTP API documentation

[Tim Bird]

On Wed, Mar 7, 2018 at 2:52 AM, Cyril Hrubis <chrubis@suse.cz> wrote:
> Hi!
>> Where is the API documentation, for stuff like tst_* and SAFE_*
>> and 'struct tst_test'
>>
>> I looked in ltp/docs and on the wiki, but couldn't seem to find it.
>
> It's named test-writing-guidelines, which arguably is a bit confusing
> but its there:
>
> ltp/doc/test-writing-guidelines.txt or
> https://github.com/linux-test-project/ltp/wiki/Test-Writing-Guidelines
>
> And we also have nice C testcase tutorial:
>
> doc/c-test-tutorial-simple.txt or
> https://github.com/linux-test-project/ltp/wiki/C-Test-Case-Tutorial

OK.  I actually had found both of these, but didn't realize that
these were intended as API documentation.  I was expecting
to see something more formal describing each routine
(maybe in an alphabetical list).  For the SAFE_ macros,
it says to look at the source for a complete list, so for these
and possibly other APIs these docs don't appear to be
comprehensive.

Would you be OK with me writing up some more formal
documentation for the APIs, and contributing them to the
project?  I probably won't get to it for a few weeks, as
I'm busy getting ready for a conference.  But it might
be nice to document these more formally and comprehensively.

 -- Tim Bird
Senior Staff Software Engineer, Sony Corporation
Architecture Group Chair, Core Embedded Linux Project, Linux Foundation

[LTP] LTP API documentation

[Cyril Hrubis]

Hi!
> OK.  I actually had found both of these, but didn't realize that
> these were intended as API documentation.  I was expecting
> to see something more formal describing each routine
> (maybe in an alphabetical list).  For the SAFE_ macros,
> it says to look at the source for a complete list, so for these
> and possibly other APIs these docs don't appear to be
> comprehensive.

Well we kept it this way for several reasons the main was that we barely
had manpower to maintain the documentation along with all the changes in
the codebase since the library API haven't been stable in the past. We
had major rewrite of the library API in the middle of 2016 by the way,
but it has been stable since with occasional additions.

We also have quite a lot of documentation in form of a header comments
so maybe it would be best just to transform it into a parseable format
and generate the formal API documentation from that. That would probably
mean changing all the comments into doxygen format and making sure every
piece of public API is documented, what do you think about that?

> Would you be OK with me writing up some more formal
> documentation for the APIs, and contributing them to the
> project?  I probably won't get to it for a few weeks, as
> I'm busy getting ready for a conference.  But it might
> be nice to document these more formally and comprehensively.

Better documetation is always welcomed, the hard part is keeping it in
sync with the code :-).

-- 
Cyril Hrubis
chrubis@suse.cz

[LTP] LTP API documentation

[Richard Palethorpe]

Hello,

Cyril Hrubis writes:

> Hi!
>> OK.  I actually had found both of these, but didn't realize that
>> these were intended as API documentation.  I was expecting
>> to see something more formal describing each routine
>> (maybe in an alphabetical list).  For the SAFE_ macros,
>> it says to look at the source for a complete list, so for these
>> and possibly other APIs these docs don't appear to be
>> comprehensive.
>
> Well we kept it this way for several reasons the main was that we barely
> had manpower to maintain the documentation along with all the changes in
> the codebase since the library API haven't been stable in the past. We
> had major rewrite of the library API in the middle of 2016 by the way,
> but it has been stable since with occasional additions.
>
> We also have quite a lot of documentation in form of a header comments
> so maybe it would be best just to transform it into a parseable format
> and generate the formal API documentation from that. That would probably
> mean changing all the comments into doxygen format and making sure every
> piece of public API is documented, what do you think about that?
>
>> Would you be OK with me writing up some more formal
>> documentation for the APIs, and contributing them to the
>> project?  I probably won't get to it for a few weeks, as
>> I'm busy getting ready for a conference.  But it might
>> be nice to document these more formally and comprehensively.
>
> Better documetation is always welcomed, the hard part is keeping it in
> sync with the code :-).
>
> -- 
> Cyril Hrubis
> chrubis@suse.cz

That sounds good to me include/tst_fuzzy_sync.h should already be in a
doxygen compatible format. I don't particularly like Doxygen though, but
there are plenty of compatible frameworks.

-- 
Thank you,
Richard.