From 2e911ee344cf8fb91dc681ddfa5f559a703e0570 Mon Sep 17 00:00:00 2001 From: Arvid Norberg Date: Sun, 21 Jul 2013 15:47:30 +0000 Subject: [PATCH] documentation polish. hide internal functions and types --- docs/gen_reference_doc.py | 23 +++++++++++++++-------- docs/style.css | 9 +-------- include/libtorrent/add_torrent_params.hpp | 1 + include/libtorrent/create_torrent.hpp | 1 + include/libtorrent/file_storage.hpp | 7 ++----- include/libtorrent/storage.hpp | 6 +++--- include/libtorrent/storage_defs.hpp | 4 ++-- 7 files changed, 25 insertions(+), 26 deletions(-) diff --git a/docs/gen_reference_doc.py b/docs/gen_reference_doc.py index 34aec8b15..215a3bcd1 100644 --- a/docs/gen_reference_doc.py +++ b/docs/gen_reference_doc.py @@ -74,8 +74,11 @@ def first_item(itr): return None def highlight_signature(s): - name = s.split('(')[0].split(' ')[-1].strip() - return s.replace(name, '' + name + '') + name = s.split('(') + name2 = name[0].split(' ') + name2[-1] = '' + name2[-1] + '' + name[0] = ' '.join(name2) + return '('.join(name) def html_sanitize(s): ret = '' @@ -221,7 +224,7 @@ def parse_class(lno, lines, filename): if looks_like_function(l): current_fun, lno = parse_function(lno - 1, lines, filename) - if current_fun != None: + if current_fun != None and context.strip() != 'internal': if context == '' and blanks == 0 and len(funs): funs[-1]['signatures'].update(current_fun['signatures']) funs[-1]['names'].update(current_fun['names']) @@ -233,6 +236,9 @@ def parse_class(lno, lines, filename): continue if looks_like_variable(l): + if context.strip() == 'internal': + context = '' + continue n = l.split(' ')[-1].split(':')[0].split(';')[0] if context == '' and blanks == 0 and len(fields): fields[-1]['names'].append(n) @@ -245,7 +251,7 @@ def parse_class(lno, lines, filename): if l.startswith('enum '): enum, lno = parse_enum(lno - 1, lines, filename) - if enum != None: + if enum != None and context.strip() != 'internal': enum['desc'] = context enums.append(enum) context = '' @@ -300,7 +306,8 @@ def parse_enum(lno, lines, filename): if verbose: print 'enumv %s' % lines[lno-1] for v in l.split(','): if v == '': continue - values.append({'name': v.strip(), 'desc': context}) + if context.strip() != 'internal': + values.append({'name': v.strip(), 'desc': context}) context = '' else: if verbose: print '?? %s' % lines[lno-1] @@ -403,7 +410,7 @@ for filename in files: if 'TORRENT_EXPORT ' in l: if 'class ' in l or 'struct ' in l: current_class, lno = parse_class(lno -1, lines, filename) - if current_class != None: + if current_class != None and context.strip() != 'internal': current_class['desc'] = context classes.append(current_class) context = '' @@ -412,7 +419,7 @@ for filename in files: if looks_like_function(l): current_fun, lno = parse_function(lno - 1, lines, filename) - if current_fun != None: + if current_fun != None and context.strip() != 'internal': if context == '' and blanks == 0 and len(functions): functions[-1]['signatures'].update(current_fun['signatures']) functions[-1]['names'].update(current_fun['names']) @@ -431,7 +438,7 @@ for filename in files: if l.startswith('enum '): current_enum, lno = parse_enum(lno - 1, lines, filename) - if current_enum != None: + if current_enum != None and context.strip() != 'internal': current_enum['desc'] = context enums.append(current_enum) context = '' diff --git a/docs/style.css b/docs/style.css index 6cbfe8456..d8bf30b49 100644 --- a/docs/style.css +++ b/docs/style.css @@ -77,14 +77,7 @@ div.section p, div.section ul, div.section dl { #container { text-align: left; - width: 700px; - margin: 0 auto; - position: relative; -} - -#container { - text-align: left; - width: 700px; + width: 70em; margin: 0 auto; position: relative; } diff --git a/include/libtorrent/add_torrent_params.hpp b/include/libtorrent/add_torrent_params.hpp index 6e9007c84..03d059e51 100644 --- a/include/libtorrent/add_torrent_params.hpp +++ b/include/libtorrent/add_torrent_params.hpp @@ -217,6 +217,7 @@ namespace libtorrent // on the torrent handle immediately after adding it. flag_sequential_download = 0x800, + // internal default_flags = flag_update_subscribe | flag_auto_managed | flag_paused | flag_apply_ip_filter #ifndef TORRENT_NO_DEPRECATE , flag_ignore_flags = 0x80000000 diff --git a/include/libtorrent/create_torrent.hpp b/include/libtorrent/create_torrent.hpp index cfa91e433..58b9869f9 100644 --- a/include/libtorrent/create_torrent.hpp +++ b/include/libtorrent/create_torrent.hpp @@ -190,6 +190,7 @@ namespace libtorrent int get_file_attributes(std::string const& p); std::string get_symlink_path(std::string const& p); + // internal TORRENT_EXPORT void add_files_impl(file_storage& fs, std::string const& p , std::string const& l, boost::function pred , boost::uint32_t flags); diff --git a/include/libtorrent/file_storage.hpp b/include/libtorrent/file_storage.hpp index 325d0371a..1a08d60ea 100644 --- a/include/libtorrent/file_storage.hpp +++ b/include/libtorrent/file_storage.hpp @@ -67,13 +67,10 @@ namespace libtorrent std::string symlink_path; }; - // this is used internally to hold the file entry - // it's smaller and optimized for smaller memory - // footprint, as opposed to file_entry, which is - // optimized for convenience - // TODO: does this really need to be exported? + // internal struct TORRENT_EXPORT internal_file_entry { + // TODO: does this really need to be exported? friend class file_storage; #ifdef TORRENT_DEBUG // for torrent_info::invariant_check diff --git a/include/libtorrent/storage.hpp b/include/libtorrent/storage.hpp index 23268d5b3..b9043748e 100644 --- a/include/libtorrent/storage.hpp +++ b/include/libtorrent/storage.hpp @@ -295,7 +295,7 @@ namespace libtorrent { // replace any files in the destination when copying // or moving the storage - always_replace_files = 0, + always_replace_files, // if any files that we want to copy exist in the destination // exist, fail the whole operation and don't perform @@ -304,11 +304,11 @@ namespace libtorrent // the operation starts. In between the check and performing // the copy, the destination files may be created, in which // case they are replaced. - fail_if_exist = 1, + fail_if_exist, // if any file exist in the target, take those files instead // of the ones we may have in the source. - dont_replace = 2, + dont_replace, }; struct disk_io_thread; diff --git a/include/libtorrent/storage_defs.hpp b/include/libtorrent/storage_defs.hpp index bfacc2f54..d981c9d3a 100644 --- a/include/libtorrent/storage_defs.hpp +++ b/include/libtorrent/storage_defs.hpp @@ -48,13 +48,13 @@ namespace libtorrent // All pieces will be written to their final position, all files will be // allocated in full when the torrent is first started. This is done with // ``fallocate()`` and similar calls. This mode minimizes fragmentation. - storage_mode_allocate = 0, + storage_mode_allocate, // All pieces will be written to the place where they belong and sparse files // will be used. This is the recommended, and default mode. storage_mode_sparse, - // internal use only + // internal internal_storage_mode_compact_deprecated, #ifndef TORRENT_NO_DEPRECATE storage_mode_compact = internal_storage_mode_compact_deprecated