[rustdoc] Rustdoc should prevent long file names.

[BenTheElder]

I'm not actually certain if handling absurdly long method names should be a goal for rustdoc, but currently they produce filenames that are too long for the filesystem. I discovered this while working with opencv-rust which auto generates c-wrapper methods for opencv, some of which have very long names. A possible proposed solution was that rustdoc abbreviate filenames, I suggest that a good solution might be splitting the name into 255 char chunks.

Eg the problem file: /home/benjamin/dev/opencv-rust/target/doc/opencv/sys/fn.cv_calib3d_cv_solvePnPRansac_InputArray_objectPoints_InputArray_imagePoints_InputArray_cameraMatrix_InputArray_distCoeffs_OutputArray_rvec_OutputArray_tvec_bool_useExtrinsicGuess_int_iterationsCount_float_reprojectionError_int_minInliersCount_OutputArray_inliers_int_flags.html

Would become something like: /home/benjamin/dev/opencv-rust/target/doc/opencv/sys/fn.cv_calib3d_cv_solvePnPRansac_InputArray_objectPoints_InputArray_imagePoints_InputArray_cameraMatrix_InputArray_distCoeffs_OutputArray_rvec_OutputArray_tvec_bool_useExtrinsicGuess_int_iterationsCount_float_reprojectionErr/or_int_minInliersCount_OutputArray_inliers_int_flags.html

Previous discussion on the rust subreddit: https://www.reddit.com/r/rust/comments/4m29tk/solution_to_file_name_too_long_for_cargo_doc/

[BenTheElder]

Small update: This also appears to be some regression of sorts, after switching back to the 1.8.0 toolchain with rustup I can document the crate as these methods are skipped.

Edit, these methods are marked #[doc(hidden)]. Perhaps then the correct answer is a way to make rustdoc not generate docs for hidden methods?

[GuillaumeGomez]

Edit, these methods are marked #[doc(hidden)]. Perhaps then the correct answer is a way to make rustdoc not generate docs for hidden methods?Edit, these methods are marked #[doc(hidden)]. Perhaps then the correct answer is a way to make rustdoc not generate docs for hidden methods?

It isn't supposed to.

[BenTheElder]

As far as I can tell, this method is in /target/debug/build/opencv-/out/calib3d.extern.rs and marked

[doc(hidden)].

It is then include!-ed in /target/debug/build/opencv-/out/hub.rs in a public sys module.

As far as I can tell now, it should be marked hidden and excluded from the docs, but 1.9.0 and nightly appear to attempt to build docs for these methods anyhow. On Jun 1, 2016 15:36, "Guillaume Gomez" notifications@github.com wrote:

Edit, these methods are marked #[doc(hidden)]. Perhaps then the correct answer is a way to make rustdoc not generate docs for hidden methods?Edit, these methods are marked #[doc(hidden)]. Perhaps then the correct answer is a way to make rustdoc not generate docs for hidden methods?

It isn't supposed to.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/rust-lang/rust/issues/34023#issuecomment-223100832, or mute the thread https://github.com/notifications/unsubscribe/AA4BqyzC_f0KZBTzAcplxERtFU9JXBgxks5qHd8jgaJpZM4Ir3Qa .

[BenTheElder]

I've opened a new issue (https://github.com/rust-lang/rust/issues/34025) to reflect what seems to be the actual problem, but I think that avoiding large file names might also be worth discussing so I will leave this open as well for now.

[retep998]

Couldn't we just shorten the name? Come up with some pattern, maybe take inspiration from DOS style short filenames, like shorten it to 100 characters and anything beyond that is replaced with ~1 or a higher number if another file has the same name, or maybe tack on a short hash of the name.

[ssokolow]

I'd go with the hash since, as long as it's well-defined (eg. take a prefix of n - hash_lengthcharacters, then hash the remaining characters using <name of hash>, then append the hash to the prefix), it's possible to re-generate it from the source materials and get the same result if necessary and it'll be more stable across runs, in case incremental rebuild is ever desired.

[steveklabnik]

Triage: no change

[workingjubilee]

As of Windows 10 patch 1607 (which happened later in 2016, actually), users can now remove the path length limitations, and patches before that are only supported for Enterprise LTSC.