documentation

(Note: I realize this is close to How do you document your database structure? , but I don't think it's identical.) I've started work at a place with a database with literally hundreds of tables and views, all with cryptic names with very few vowels, and no documentation. They also don't allow gratuitous changes to the database schema, nor can I touch any database except the test one on my own machine (which gets blown away and recreated regularly), so I can't add comments that would help anybody. I tried using "Toad" to create an ER diagram, but after leaving it running for 48 hours straight

Ok, so I've read both PEP 8 and PEP 257 , and I've written lots of docstrings for functions and classes, but I'm a little unsure about what should go in a module docstring. I figured, at a minimum, it should document the functions and classes that the module exports, but I've also seen a few modules that list author names, copyright information, etc. Does anyone have an example of how a good python docstring should be structured? Alex Martelli Think about somebody doing help(yourmodule) at the interactive interpreter's prompt — what do they want to know? (Other methods of extracting and

The Apple ObjectiveC description implies that NSStrings exist by showing examples, and that NSString literals are written as @ "<string content>" Amazingly, that's all it says, and these only show up in examples without any discussion. Is that document really the only reference document? Digging around, I found this blog which seems to have a lot of useful information. But is it right? Is there an authoritative document describing precisely what one can say (syntax) in an NSString literal, and what it means (semantics)? For instance, is the syntax of the content of a NSString literal identical

I'm playing around with a small crate for 2D noise generation. Here is a simplified snippet of my "lib.rs" file: pub mod my_math { pub struct Vec2<T> { ... } ... } pub mod my_noise { use num::Float; use std::num::Wrapping; use my_math::*; /// Gets pseudo-random noise based on a seed vector. /// /// # Examples /// /// ``` /// use my_math::Vec2; /// /// let v_seed = Vec2::<f32>::new_values(4.134, -23.141); /// let noise_val = get_noise_white(&v_seed); /// /// assert!(noise_val >= 0.0); /// assert!(noise_val <= 1.0); /// ``` pub fn get_noise_white(seed: &Vec2<f32>) -> f32 { ... } } However, when

In order to ensure that all public artifacts of my crate are documented (if minimally to start with), I specified #![deny(missing_docs)] in my lib.rs . This backfired. I expected to write a documentation comment at the top and the code afterwards: /// Hello world example for Rust. #![deny(missing_docs)] fn main() { println!("Hello world!"); } This fails with: error: an inner attribute is not permitted following an outer doc comment --> src/main.rs:3:3 | 3 | #![deny(missing_docs)] | ^ | = note: inner attributes, like `#![no_std]`, annotate the item enclosing them, and are usually found at the

I'm developing a JavaEE system (distributed on Weblogic App Server), but I don't have the sources for the JavaEE packages (javax.ejb.*, for instance). Where can I find the sources (not javadoc) for these packages? Java EE is an abstract API. It exist of just contracts (as you see in javadocs), not concrete code. The application servers are the concrete implementations. So, if you're looking for the source, you should look at the application server vendor's homepage for a source code download link. However, you're unlucky with Weblogic. It is not open source. I've never used Weblogic (I am an

How do I document class constants for phpDoc? I've read the manual but I can't find anything about them. I'm fairly sure that you can use @const , though I can't find any English documentation. There's a German example here . It shows define statements rather than class constants, but IIRC the syntax is the same. Nine years later, an edit... It is clear now that the above is bad advice as @const has not appeared in the docs and it seems it will not. Using @var seems to work, though I cannot see it explicitly specified anywhere. ashnazg Constants only need a docblock that contains the

I am using something similar to this and it will not display the Summary or Remarks when I am attempting to use the Intellisense for this function? ''' <summary> ''' Summary ''' </summary> ''' <param name="param">The Parameter.</param> ''' <remarks> Remarks </remarks> any ideas? Need to goto Projects -> Project Properties -> Compile and turn on XML Generated File to generate the comments file.. Then build your project and it will work =) 来源： https://stackoverflow.com/questions/1329338/xml-comments-not-showing-on-vb-net