| Message ID | 1438797911-7957-1-git-send-email-mike.holmes@linaro.org |
|---|---|
| State | New |
| Headers | show |
On Wed, Aug 05, 2015 at 02:05:11PM -0400, Mike Holmes wrote: > Doxygen can create a perl module that is a hash of the entire API. > Set the flag to generate this so that tools may analyse differences in > the API between different repositories branches and tags. > > The benefits are: > - This can allow CI to generate nightly data such as the difference > between api-next and master to track API change. > - It can also work with the check-odp scripts to ensure that any patch > that touches the API is only accepted into api-next. > - It can verify that implementations ship with an API that > matches the linux-generic reference when compatibility with a > specific API version is required. > - Release notes can list the differences in the API from the previous > version > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > --- > doc/doxygen.cfg | 1 + > 1 file changed, 1 insertion(+) > > diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg > index f28ec24..001d315 100644 > --- a/doc/doxygen.cfg > +++ b/doc/doxygen.cfg > @@ -45,3 +45,4 @@ PREDEFINED = __GNUC__ \ > ODP_PACKED \ > "ODP_HANDLE_T(type)=odp_handle_t type" > INTERNAL_DOCS = YES > +GENERATE_PERLMOD = YES > -- > 2.1.4 > This has just reminded me that I wrote a python script some time last year to compare APIs, with the intention then being to check for differences between platforms (back when the headers were copied). It uses GENERATE_XML and I was able to run it against master<->api-next with a couple of small tweaks due to paths changing, output is; # odp_docs_check include/odp/api/ doc/output/xml/ ../odp-api-next/doc/output/xml/ pool.h ODP_POOL_NAME_LEN documentation differs event.h odp_event_type documentation differs init.h odp_init_global documentation differs init.h odp_init_local documentation differs packet_io.h odp_pktio_open documentation differs packet_io.h odp_pktio_start missing in doc/output/xml/ packet_io.h odp_pktio_stop missing in doc/output/xml/ pool.h odp_pool_param_init missing in doc/output/xml/ queue.h odp_queue_context missing in doc/output/xml/ queue.h odp_queue_context_set missing in doc/output/xml/ queue.h odp_queue_get_context missing in ../odp-api-next/doc/output/xml/ queue.h odp_queue_param_init missing in doc/output/xml/ queue.h odp_queue_sched_type documentation differs queue.h odp_queue_set_context missing in ../odp-api-next/doc/output/xml/ schedule.h odp_schedule documentation differs schedule.h odp_schedule_group_create missing in doc/output/xml/ schedule.h odp_schedule_group_destroy missing in doc/output/xml/ schedule.h odp_schedule_olock_init missing in doc/output/xml/ schedule.h odp_schedule_olock_lock missing in doc/output/xml/ schedule.h odp_schedule_olock_unlock missing in doc/output/xml/ schedule.h odp_schedule_prefetch missing in doc/output/xml/ schedule.h odp_schedule_release_atomic documentation differs schedule.h odp_schedule_release_ordered missing in doc/output/xml/ init.h odp_term_global documentation differs init.h odp_term_local documentation differs 379 APIs checked, 25 didn't match! I suspect it's not picking up the stuff in the _types.h files though.
On 08/06/15 14:02, Stuart Haslam wrote: > On Wed, Aug 05, 2015 at 02:05:11PM -0400, Mike Holmes wrote: >> Doxygen can create a perl module that is a hash of the entire API. >> Set the flag to generate this so that tools may analyse differences in >> the API between different repositories branches and tags. >> >> The benefits are: >> - This can allow CI to generate nightly data such as the difference >> between api-next and master to track API change. >> - It can also work with the check-odp scripts to ensure that any patch >> that touches the API is only accepted into api-next. >> - It can verify that implementations ship with an API that >> matches the linux-generic reference when compatibility with a >> specific API version is required. >> - Release notes can list the differences in the API from the previous >> version >> >> Signed-off-by: Mike Holmes <mike.holmes@linaro.org> >> --- >> doc/doxygen.cfg | 1 + >> 1 file changed, 1 insertion(+) >> >> diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg >> index f28ec24..001d315 100644 >> --- a/doc/doxygen.cfg >> +++ b/doc/doxygen.cfg >> @@ -45,3 +45,4 @@ PREDEFINED = __GNUC__ \ >> ODP_PACKED \ >> "ODP_HANDLE_T(type)=odp_handle_t type" >> INTERNAL_DOCS = YES >> +GENERATE_PERLMOD = YES >> -- >> 2.1.4 >> > This has just reminded me that I wrote a python script some time last > year to compare APIs, with the intention then being to check for > differences between platforms (back when the headers were copied). > > It uses GENERATE_XML and I was able to run it against master<->api-next > with a couple of small tweaks due to paths changing, output is; > > # odp_docs_check include/odp/api/ doc/output/xml/ ../odp-api-next/doc/output/xml/ > > pool.h ODP_POOL_NAME_LEN documentation differs > event.h odp_event_type documentation differs > init.h odp_init_global documentation differs > init.h odp_init_local documentation differs > packet_io.h odp_pktio_open documentation differs > packet_io.h odp_pktio_start missing in doc/output/xml/ > packet_io.h odp_pktio_stop missing in doc/output/xml/ > pool.h odp_pool_param_init missing in doc/output/xml/ > queue.h odp_queue_context missing in doc/output/xml/ > queue.h odp_queue_context_set missing in doc/output/xml/ > queue.h odp_queue_get_context missing in ../odp-api-next/doc/output/xml/ > queue.h odp_queue_param_init missing in doc/output/xml/ > queue.h odp_queue_sched_type documentation differs > queue.h odp_queue_set_context missing in ../odp-api-next/doc/output/xml/ > schedule.h odp_schedule documentation differs > schedule.h odp_schedule_group_create missing in doc/output/xml/ > schedule.h odp_schedule_group_destroy missing in doc/output/xml/ > schedule.h odp_schedule_olock_init missing in doc/output/xml/ > schedule.h odp_schedule_olock_lock missing in doc/output/xml/ > schedule.h odp_schedule_olock_unlock missing in doc/output/xml/ > schedule.h odp_schedule_prefetch missing in doc/output/xml/ > schedule.h odp_schedule_release_atomic documentation differs > schedule.h odp_schedule_release_ordered missing in doc/output/xml/ > init.h odp_term_global documentation differs > init.h odp_term_local documentation differs > > 379 APIs checked, 25 didn't match! > > I suspect it's not picking up the stuff in the _types.h files though. > interesting stats. we can generate it and put to web page. Maxim. > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp
This one generate output like attached by module or file, and has flags to see full docs, functions, enums etc Diffs looks like this diff --recursive --new-file -s -d home_mike_git_odp-module/odp_buffer home_mike_git_odp-test-module/odp_buffer 28a29 > enum odp_pool_type_t odp_pool_type_t Files home_mike_git_odp-module/odp_classification and home_mike_git_odp-test-module/odp_classification are identical Files home_mike_git_odp-module/odp_compiler_optim and home_mike_git_odp-test-module/odp_compiler_optim are identical Files home_mike_git_odp-module/odp_config and home_mike_git_odp-test-module/odp_config are identical Files home_mike_git_odp-module/odp_cpu and home_mike_git_odp-test-module/odp_cpu are identical Files home_mike_git_odp-module/odp_cpumask and home_mike_git_odp-test-module/odp_cpumask are identical Files home_mike_git_odp-module/odp_crypto and home_mike_git_odp-test-module/odp_crypto are identical Files home_mike_git_odp-module/odp_errno and home_mike_git_odp-test-module/odp_errno are identical diff --recursive --new-file -s -d home_mike_git_odp-module/odp_event home_mike_git_odp-test-module/odp_event 5c5 < int odp_event_type (odp_event_t event) --- > odp_event_type_t odp_event_type (odp_event_t event) 13a14 > enum odp_event_type_t odp_event_type_t 18,25d18 < ODP_EVENT_BUFFER < Buffer event. < ODP_EVENT_PACKET < Packet event. < ODP_EVENT_TIMEOUT < Timeout event. < ODP_EVENT_CRYPTO_COMPL < Crypto completion event. Files home_mike_git_odp-module/odph_header and home_mike_git_odp-test-module/odph_header are identical diff --recursive --new-file -s -d home_mike_git_odp-module/odp_initialization home_mike_git_odp-test-module/odp_initialization 9,10c9,10 < int odp_init_global (odp_init_t * params,odp_platform_init_t * platform_params) < Perform global ODP initialization. --- > int odp_init_global (const odp_init_t * params,const odp_platform_init_t * platform_params) > Global ODP initialization. On 6 August 2015 at 07:02, Stuart Haslam <stuart.haslam@linaro.org> wrote: > On Wed, Aug 05, 2015 at 02:05:11PM -0400, Mike Holmes wrote: > > Doxygen can create a perl module that is a hash of the entire API. > > Set the flag to generate this so that tools may analyse differences in > > the API between different repositories branches and tags. > > > > The benefits are: > > - This can allow CI to generate nightly data such as the difference > > between api-next and master to track API change. > > - It can also work with the check-odp scripts to ensure that any patch > > that touches the API is only accepted into api-next. > > - It can verify that implementations ship with an API that > > matches the linux-generic reference when compatibility with a > > specific API version is required. > > - Release notes can list the differences in the API from the previous > > version > > > > Signed-off-by: Mike Holmes <mike.holmes@linaro.org> > > --- > > doc/doxygen.cfg | 1 + > > 1 file changed, 1 insertion(+) > > > > diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg > > index f28ec24..001d315 100644 > > --- a/doc/doxygen.cfg > > +++ b/doc/doxygen.cfg > > @@ -45,3 +45,4 @@ PREDEFINED = __GNUC__ \ > > ODP_PACKED \ > > "ODP_HANDLE_T(type)=odp_handle_t type" > > INTERNAL_DOCS = YES > > +GENERATE_PERLMOD = YES > > -- > > 2.1.4 > > > > This has just reminded me that I wrote a python script some time last > year to compare APIs, with the intention then being to check for > differences between platforms (back when the headers were copied). > > It uses GENERATE_XML and I was able to run it against master<->api-next > with a couple of small tweaks due to paths changing, output is; > > # odp_docs_check include/odp/api/ doc/output/xml/ > ../odp-api-next/doc/output/xml/ > > pool.h ODP_POOL_NAME_LEN documentation differs > event.h odp_event_type documentation differs > init.h odp_init_global documentation differs > init.h odp_init_local documentation differs > packet_io.h odp_pktio_open documentation differs > packet_io.h odp_pktio_start missing in > doc/output/xml/ > packet_io.h odp_pktio_stop missing in > doc/output/xml/ > pool.h odp_pool_param_init missing in > doc/output/xml/ > queue.h odp_queue_context missing in > doc/output/xml/ > queue.h odp_queue_context_set missing in > doc/output/xml/ > queue.h odp_queue_get_context missing in > ../odp-api-next/doc/output/xml/ > queue.h odp_queue_param_init missing in > doc/output/xml/ > queue.h odp_queue_sched_type documentation differs > queue.h odp_queue_set_context missing in > ../odp-api-next/doc/output/xml/ > schedule.h odp_schedule documentation differs > schedule.h odp_schedule_group_create missing in > doc/output/xml/ > schedule.h odp_schedule_group_destroy missing in > doc/output/xml/ > schedule.h odp_schedule_olock_init missing in > doc/output/xml/ > schedule.h odp_schedule_olock_lock missing in > doc/output/xml/ > schedule.h odp_schedule_olock_unlock missing in > doc/output/xml/ > schedule.h odp_schedule_prefetch missing in > doc/output/xml/ > schedule.h odp_schedule_release_atomic documentation differs > schedule.h odp_schedule_release_ordered missing in > doc/output/xml/ > init.h odp_term_global documentation differs > init.h odp_term_local documentation differs > > 379 APIs checked, 25 didn't match! > > I suspect it's not picking up the stuff in the _types.h files though. > > -- > Stuart. >
On Thu, Aug 06, 2015 at 07:22:09AM -0400, Mike Holmes wrote: > This one generate output like attached by module or file, and has flags to > see full docs, functions, enums etc > But python is better than perl.. :) Just kidding, I've no problem putting my script back in the forgotten pile of code it came from.
On 08/06/15 14:55, Stuart Haslam wrote: > On Thu, Aug 06, 2015 at 07:22:09AM -0400, Mike Holmes wrote: >> This one generate output like attached by module or file, and has flags to >> see full docs, functions, enums etc >> > But python is better than perl.. :) a lot of people can write perl code but only few of them can read that code :) > > Just kidding, I've no problem putting my script back in the forgotten > pile of code it came from. >
diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg index f28ec24..001d315 100644 --- a/doc/doxygen.cfg +++ b/doc/doxygen.cfg @@ -45,3 +45,4 @@ PREDEFINED = __GNUC__ \ ODP_PACKED \ "ODP_HANDLE_T(type)=odp_handle_t type" INTERNAL_DOCS = YES +GENERATE_PERLMOD = YES
Doxygen can create a perl module that is a hash of the entire API. Set the flag to generate this so that tools may analyse differences in the API between different repositories branches and tags. The benefits are: - This can allow CI to generate nightly data such as the difference between api-next and master to track API change. - It can also work with the check-odp scripts to ensure that any patch that touches the API is only accepted into api-next. - It can verify that implementations ship with an API that matches the linux-generic reference when compatibility with a specific API version is required. - Release notes can list the differences in the API from the previous version Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- doc/doxygen.cfg | 1 + 1 file changed, 1 insertion(+)